Contacts

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.

POST

blocked_handles

Block a handle

curl --request POST \
  --url https://api.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>"
}

Authorizations

Authorization

string

header

required

Bearer token authentication. Include your API token in the Authorization header.

Format: Authorization: Bearer <your-token>

Body

application/json

handle

string

required

Registered Relay Handle.

Required string length: 1 - 255

reason

string

Optional free-text note on why the handle was blocked

Required string length: 1 - 500

Response

Handle blocked successfully

blocked_handle

object

required

Show child attributes

Block a handle

curl --request POST \
  --url https://api.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>"
}

Overview

Chats

Messages

Attachments

Contacts

Webhooks

WebSocket

Agents

Block a handle

Authorizations

Body

Response