Chats

Send a message to an existing chat

Send a Message to an existing Chat.

Blocking is silent on this path. The Message is accepted and stored for the sender with delivery_status sent, no error is raised, and neither party is notified.

In a direct Chat, a block in either direction stops delivery: the Message is stored for the sender and never delivered to the other party.

In a group Chat, blocking is one way. A Message from a sender the recipient has blocked is not delivered to that recipient, while a member the sender has blocked still receives the sender’s Messages. Every other member receives the Message 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, and it is never replayed after an unblock. The sender’s message.delivered fires when at least one recipient was delivered.

POST

chats

{chatId}

messages

Send a message to an existing chat

curl --request POST \
  --url https://api.relayapp.im/v1/chats/{chatId}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": {
    "parts": [
      {
        "type": "text",
        "value": "<string>",
        "mention": "<string>",
        "mention_range": "<array>"
      }
    ],
    "idempotency_key": "<string>",
    "silent": false
  }
}
'

{
  "chat_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "message": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "parts": [
      {
        "type": "text",
        "value": "<string>",
        "reactions": [
          {
            "is_me": true,
            "handle": {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "handle": "<string>",
              "joined_at": "2023-11-07T05:31:56Z",
              "kind": "user",
              "display_name": "<string>",
              "image_url": "<string>",
              "image_color": "<string>",
              "about": "<string>",
              "verified": true,
              "is_contact": true,
              "status": "active",
              "left_at": "2023-11-07T05:31:56Z",
              "is_me": true
            },
            "type": "love",
            "custom_emoji": "<string>"
          }
        ],
        "mentions": [
          {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "handle": "<string>",
            "is_me": true,
            "range": [
              1
            ]
          }
        ],
        "mention": "<string>",
        "mention_range": "<array>"
      }
    ],
    "created_at": "2023-11-07T05:31:56Z",
    "sent_at": "2023-11-07T05:31:56Z",
    "delivery_status": "sent",
    "delivered_at": "2023-11-07T05:31:56Z",
    "from_handle": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "handle": "<string>",
      "joined_at": "2023-11-07T05:31:56Z",
      "kind": "user",
      "display_name": "<string>",
      "image_url": "<string>",
      "image_color": "<string>",
      "about": "<string>",
      "verified": true,
      "is_contact": true,
      "status": "active",
      "left_at": "2023-11-07T05:31:56Z",
      "is_me": true
    },
    "silent": true,
    "reply_to": {
      "message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "part_index": 1
    },
    "thread": {
      "originator_message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "originator_part_index": 1
    }
  }
}

{
  "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": 403,
    "code": 2028,
    "message": "A chat must include an agent.",
    "doc_url": "https://docs.relayapp.im/error/codes/2xxx/2028"
  },
  "success": false
}

{
  "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>

Headers

Idempotency-Key

string

Optional 1–255 character key for safe retries. If message.idempotency_key is also present, the two values must match.

Required string length: 1 - 255

Path Parameters

chatId

string<uuid>

required

Unique identifier of the chat

Body

application/json

message

object

required

One message containing 1–100 ordered text, media, or link parts. A link must be the only part.

Show child attributes

Response

Message accepted for delivery

Response for sending a message to a chat

chat_id

string<uuid>

required

Unique identifier of the chat this message was sent to

message

object

required

A message that was sent (used in CreateChat and SendMessage responses)

Show child attributes

Send a message to an existing chat

curl --request POST \
  --url https://api.relayapp.im/v1/chats/{chatId}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": {
    "parts": [
      {
        "type": "text",
        "value": "<string>",
        "mention": "<string>",
        "mention_range": "<array>"
      }
    ],
    "idempotency_key": "<string>",
    "silent": false
  }
}
'

{
  "chat_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "message": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "parts": [
      {
        "type": "text",
        "value": "<string>",
        "reactions": [
          {
            "is_me": true,
            "handle": {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "handle": "<string>",
              "joined_at": "2023-11-07T05:31:56Z",
              "kind": "user",
              "display_name": "<string>",
              "image_url": "<string>",
              "image_color": "<string>",
              "about": "<string>",
              "verified": true,
              "is_contact": true,
              "status": "active",
              "left_at": "2023-11-07T05:31:56Z",
              "is_me": true
            },
            "type": "love",
            "custom_emoji": "<string>"
          }
        ],
        "mentions": [
          {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "handle": "<string>",
            "is_me": true,
            "range": [
              1
            ]
          }
        ],
        "mention": "<string>",
        "mention_range": "<array>"
      }
    ],
    "created_at": "2023-11-07T05:31:56Z",
    "sent_at": "2023-11-07T05:31:56Z",
    "delivery_status": "sent",
    "delivered_at": "2023-11-07T05:31:56Z",
    "from_handle": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "handle": "<string>",
      "joined_at": "2023-11-07T05:31:56Z",
      "kind": "user",
      "display_name": "<string>",
      "image_url": "<string>",
      "image_color": "<string>",
      "about": "<string>",
      "verified": true,
      "is_contact": true,
      "status": "active",
      "left_at": "2023-11-07T05:31:56Z",
      "is_me": true
    },
    "silent": true,
    "reply_to": {
      "message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "part_index": 1
    },
    "thread": {
      "originator_message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "originator_part_index": 1
    }
  }
}

{
  "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": 403,
    "code": 2028,
    "message": "A chat must include an agent.",
    "doc_url": "https://docs.relayapp.im/error/codes/2xxx/2028"
  },
  "success": false
}

{
  "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

Send a message to an existing chat

Authorizations

Headers

Path Parameters

Body

Response