Messages

Resolve a Chat and send a Message

Resolve or create a Chat, then send a Message.

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

messages

Resolve a Chat and send a Message

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

{
  "chat_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_new_chat": true,
  "from": "<string>",
  "is_group": true,
  "handles": [
    {
      "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
    }
  ],
  "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
    }
  }
}

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 idempotency key for the send. Reuse the same key to safely retry without sending twice. May also be supplied as message.idempotency_key.

Maximum string length: 255

Body

application/json

Resolve or reuse the Chat for the recipient Handles, then send a Message as the authenticated Contact.

string[]

required

Required array length: 1 - 6 elements

message

object

required

The Message to send. Text, link, and media parts are supported. Voice memos use POST /v1/chats/{chatId}/voicememo.

Show child attributes

Response

Message accepted for delivery

The resolved Chat and resulting Message.

chat_id

string<uuid>

required

The reused or newly created Chat.

created_new_chat

boolean

required

from

string

required

Handle of the authenticated sending Contact.

is_group

boolean

required

Whether the resolved chat is a group chat.

handles

object[]

required

Contacts in the resolved Chat.

Show child attributes

message

object

required

The primary message that was sent.

Show child attributes

Resolve a Chat and send a Message

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

{
  "chat_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_new_chat": true,
  "from": "<string>",
  "is_group": true,
  "handles": [
    {
      "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
    }
  ],
  "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
    }
  }
}

Overview

Chats

Messages

Attachments

Contacts

Webhooks

WebSocket

Agents

Resolve a Chat and send a Message

Authorizations

Headers

Body

Response