Block a handle
Block a registered Relay Handle.
In a direct Chat, a block in either direction stops delivery. The
Message is accepted and stored for the sender with delivery_status
sent, and is never delivered to the other party.
In a group Chat, blocking is one way. Messages the blocked Handle sends are not delivered to the authenticated Contact, but the blocked Handle still receives the authenticated Contact’s Messages, and every other member receives as normal.
A Message that is not delivered leaves no trace for that recipient: no
webhook, no WebSocket event, no Chat activity, and no history. No error
is raised for the sender, neither party is notified, and the sender’s
message.delivered fires when at least one recipient was delivered.
Blocking does not delete existing Chats or history. It only stops new traffic.
Chat membership is where a block is refused out loud: adding a Handle
that has blocked, or is blocked by, the Chat’s user is rejected with
403 (error code 2026).
reason is a free-text note returned on the list endpoint. Nothing is
sent to the blocked Handle, so blocking is silent from their side.
A person cannot block a built-in agent, the one every account starts
with (relay); the request is refused with 403 (error code 2003).
curl --request POST \
--url https://api.staging.relayapp.im/v1/blocked_handles \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"handle": "<string>"
}
'{
"blocked_handle": {
"handle": "<string>",
"blocked_at": "2023-11-07T05:31:56Z",
"reason": "<string>"
}
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}Authorizations
Bearer token authentication. Include your API token in the Authorization header.
Format: Authorization: Bearer <your-token>
Body
Response
Handle blocked successfully
Show child attributes
Show child attributes
curl --request POST \
--url https://api.staging.relayapp.im/v1/blocked_handles \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"handle": "<string>"
}
'{
"blocked_handle": {
"handle": "<string>",
"blocked_at": "2023-11-07T05:31:56Z",
"reason": "<string>"
}
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}