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
/
v1
/
chats
/
{chatId}
/
messages
Send a message to an existing chat
curl --request POST \
--url https://api.staging.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>",
"subtitle": "<string>",
"verified": true,
"is_contact": true,
"status": "active",
"left_at": "2023-11-07T05:31:56Z",
"is_me": true,
"owner": {
"kind": "organization",
"name": "<string>",
"verified": true
},
"rive": {
"file": "https://cdn.relayapp.im/rive/0199a000-0000-7000-8000-00000000000b/1790000000000/file-0123456789abcdef.riv",
"artboard": "Call",
"state_machine": "Main",
"view_model": "Main"
},
"timezone": "America/Detroit",
"age_range": "18_plus",
"links": [
"https://github.com/ana",
"https://www.instagram.com/ana"
],
"about": "Builds robots in Ann Arbor.",
"activity_version": "<string>",
"activity": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>",
"emoji": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z"
}
},
"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>",
"subtitle": "<string>",
"verified": true,
"is_contact": true,
"status": "active",
"left_at": "2023-11-07T05:31:56Z",
"is_me": true,
"owner": {
"kind": "organization",
"name": "<string>",
"verified": true
},
"rive": {
"file": "https://cdn.relayapp.im/rive/0199a000-0000-7000-8000-00000000000b/1790000000000/file-0123456789abcdef.riv",
"artboard": "Call",
"state_machine": "Main",
"view_model": "Main"
},
"timezone": "America/Detroit",
"age_range": "18_plus",
"links": [
"https://github.com/ana",
"https://www.instagram.com/ana"
],
"about": "Builds robots in Ann Arbor.",
"activity_version": "<string>",
"activity": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>",
"emoji": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z"
}
},
"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.staging.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>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 429,
"code": 2008,
"message": "Too many messages. Try again shortly.",
"doc_url": "https://docs.staging.relayapp.im/error/codes/2xxx/2008",
"retry_after": 10
},
"success": false
}{
"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>
Headers
Optional 1–255 character key for safe retries. If message.idempotency_key is also present, the two values must match.
Required string length:
1 - 255Path Parameters
Unique identifier of the chat
Body
application/json
One message containing 1–100 ordered parts. A link must be the only part. A selection needs no text part; it carries its own title, and a text part beside it is an ordinary message. Selection responses contain exactly plain text then selection_response metadata and require an explicit reply target. A message carries at most one rich_card or carousel; a card reply is exactly plain text then suggestion_response, replying to the card part. Form responses contain exactly Form sent plain text then form_response metadata with answers keyed by field id, and require an explicit reply target.
Show child attributes
Show child attributes
⌘I
Send a message to an existing chat
curl --request POST \
--url https://api.staging.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>",
"subtitle": "<string>",
"verified": true,
"is_contact": true,
"status": "active",
"left_at": "2023-11-07T05:31:56Z",
"is_me": true,
"owner": {
"kind": "organization",
"name": "<string>",
"verified": true
},
"rive": {
"file": "https://cdn.relayapp.im/rive/0199a000-0000-7000-8000-00000000000b/1790000000000/file-0123456789abcdef.riv",
"artboard": "Call",
"state_machine": "Main",
"view_model": "Main"
},
"timezone": "America/Detroit",
"age_range": "18_plus",
"links": [
"https://github.com/ana",
"https://www.instagram.com/ana"
],
"about": "Builds robots in Ann Arbor.",
"activity_version": "<string>",
"activity": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>",
"emoji": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z"
}
},
"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>",
"subtitle": "<string>",
"verified": true,
"is_contact": true,
"status": "active",
"left_at": "2023-11-07T05:31:56Z",
"is_me": true,
"owner": {
"kind": "organization",
"name": "<string>",
"verified": true
},
"rive": {
"file": "https://cdn.relayapp.im/rive/0199a000-0000-7000-8000-00000000000b/1790000000000/file-0123456789abcdef.riv",
"artboard": "Call",
"state_machine": "Main",
"view_model": "Main"
},
"timezone": "America/Detroit",
"age_range": "18_plus",
"links": [
"https://github.com/ana",
"https://www.instagram.com/ana"
],
"about": "Builds robots in Ann Arbor.",
"activity_version": "<string>",
"activity": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"text": "<string>",
"emoji": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z"
}
},
"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.staging.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>"
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}{
"error": {
"status": 429,
"code": 2008,
"message": "Too many messages. Try again shortly.",
"doc_url": "https://docs.staging.relayapp.im/error/codes/2xxx/2008",
"retry_after": 10
},
"success": false
}{
"error": {
"status": 123,
"code": 123,
"message": "<string>",
"doc_url": "<string>",
"retry_after": 123
},
"success": true,
"trace_id": "<string>"
}