Messages API

The Messages API allows you to send messages via configured messaging channels (Signal, Telegram, Discord, etc.).

Send Message

Send a message to a recipient via a messaging channel.

Method: `send`

Request:

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "send",
  "params": {
    "to": "+1234567890",
    "message": "Hello from OpenClaw!",
    "channel": "signal",
    "idempotencyKey": "unique-key-123"
  }
}

string

required

Recipient identifier (phone number, user ID, username, etc.)

string

Text message content (at least one of message, mediaUrl, or mediaUrls required)

string

Channel ID (e.g., "signal", "telegram", "discord", "slack")

string

required

Unique key to prevent duplicate sends

string

Single media attachment URL

array

Array of media attachment URLs

boolean

default:false

Enable GIF playback (for animated GIFs)

string

Account ID for multi-account channels

string

Thread ID for threaded messages

string

Session key for tracking conversation context

Response:

{
  "id": 20,
  "ok": true,
  "payload": {
    "sent": true,
    "messageId": "msg-123"
  }
}

boolean

Whether the message was sent successfully

string

Platform-specific message identifier

boolean

Whether the response was cached (idempotency)

Send Message with Media

Send messages with image, video, or document attachments.

Single Media Attachment

{
  "jsonrpc": "2.0",
  "id": 21,
  "method": "send",
  "params": {
    "to": "+1234567890",
    "message": "Check out this image!",
    "mediaUrl": "https://example.com/image.jpg",
    "channel": "signal",
    "idempotencyKey": "unique-key-124"
  }
}

Multiple Media Attachments

{
  "jsonrpc": "2.0",
  "id": 22,
  "method": "send",
  "params": {
    "to": "+1234567890",
    "message": "Photo album:",
    "mediaUrls": [
      "https://example.com/photo1.jpg",
      "https://example.com/photo2.jpg",
      "https://example.com/photo3.jpg"
    ],
    "channel": "signal",
    "idempotencyKey": "unique-key-125"
  }
}

Media-Only Message

{
  "jsonrpc": "2.0",
  "id": 23,
  "method": "send",
  "params": {
    "to": "+1234567890",
    "mediaUrl": "https://example.com/document.pdf",
    "channel": "signal",
    "idempotencyKey": "unique-key-126"
  }
}

Idempotency

The idempotencyKey parameter ensures duplicate messages are not sent:

Same idempotencyKey within a short time window returns cached result
Prevents accidental duplicate sends
Returns cached: true in response metadata

Example cached response:

{
  "id": 20,
  "ok": true,
  "payload": {
    "sent": true,
    "messageId": "msg-123"
  },
  "meta": {
    "cached": true
  }
}

Channels

Available channels depend on your configuration:

Channel	ID	Recipient Format
Signal	`signal`	Phone number (E.164): `"+1234567890"`
Telegram	`telegram`	User ID or username: `"@username"`
Discord	`discord`	User ID or channel ID
Slack	`slack`	User ID or channel ID: `"#channel"`
WhatsApp	`whatsapp`	Phone number (E.164)
iMessage	`imessage`	Phone number or email

See Channels for configuration details.

Message Routing

OpenClaw automatically routes messages based on:

Explicit channel - Use channel parameter
Session key prefix - Extract channel from session key (e.g., "signal:+1234567890")
Default channel - Use configured default channel

Example with session key routing:

{
  "method": "send",
  "params": {
    "to": "+1234567890",
    "message": "Hello!",
    "sessionKey": "signal:+1234567890",
    "idempotencyKey": "key-127"
  }
}

Channel is inferred from signal: prefix.

Polls

Send interactive polls via supported channels.

Method: `poll`

{
  "jsonrpc": "2.0",
  "id": 24,
  "method": "poll",
  "params": {
    "to": "+1234567890",
    "question": "What's your favorite color?",
    "options": ["Red", "Blue", "Green"],
    "channel": "signal",
    "idempotencyKey": "poll-123"
  }
}

string

required

Poll question

array

required

Array of poll options (strings)

string

required

Recipient identifier

string

Channel ID

string

required

Unique key for idempotency

boolean

default:false

Allow multiple selections

boolean

default:false

Hide voter identities

Error Handling

Missing recipient:

{
  "ok": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required parameter: to"
  }
}

Channel not configured:

{
  "ok": false,
  "error": {
    "code": "CHANNEL_NOT_FOUND",
    "message": "Channel 'signal' is not configured"
  }
}

Delivery failed:

{
  "ok": false,
  "error": {
    "code": "DELIVERY_FAILED",
    "message": "Failed to send message: recipient not found"
  }
}

Example: Send with Media

curl -X POST http://localhost:18789/api/send \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "send",
    "params": {
      "to": "+1234567890",
      "message": "Check this out!",
      "mediaUrl": "https://example.com/photo.jpg",
      "channel": "signal",
      "idempotencyKey": "msg-'$(date +%s)'"
    }
  }'

Example: JavaScript Client

const ws = new WebSocket('ws://localhost:18789');
let requestId = 0;

function sendMessage(to, message, channel = 'signal') {
  const id = ++requestId;
  const idempotencyKey = `msg-${Date.now()}-${id}`;
  
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    id,
    method: "send",
    params: { to, message, channel, idempotencyKey }
  }));
  
  return id;
}

ws.on('open', () => {
  // Authenticate first
  ws.send(JSON.stringify({
    jsonrpc: "2.0",
    id: 0,
    method: "connect",
    params: {
      role: 'control',
      auth: { token: 'your-token' },
      client: { name: 'Sender', version: '1.0.0' }
    }
  }));
});

ws.on('message', (data) => {
  const frame = JSON.parse(data);
  
  if (frame.id === 0 && frame.ok) {
    // Connected - send message
    sendMessage('+1234567890', 'Hello from WebSocket!');
  } else if (frame.id > 0) {
    console.log('Message sent:', frame.payload);
  }
});

Message Format

Messages support basic formatting depending on the channel: Markdown (Signal, Telegram, Discord, Slack):

**bold** _italic_ `code` [link](https://example.com)

Mentions:

@username mentioned you!

Emojis:

Hello! 👋

Formatting support varies by channel. See individual channel documentation.

Best Practices

Always use idempotency keys

Generate unique keys to prevent duplicate sends:

const idempotencyKey = `msg-${Date.now()}-${Math.random()}`;

Validate recipients

Ensure phone numbers are in E.164 format:

+1234567890  ✓
1234567890   ✗
(123)456-7890 ✗

Handle media URLs correctly

Use publicly accessible URLs
Ensure HTTPS for secure content
Check file size limits per channel

Check channel status

Verify channel is logged in before sending:

{"method": "channels.status", "params": {}}

Next Steps

Channels

Configure messaging channels

Sessions

Manage conversation sessions

Agent Protocol

Invoke agents to generate responses

Gateway API

Agent Communication

Messages

Messages API

Send Message

Method: `send`

Send Message with Media

Single Media Attachment

Multiple Media Attachments

Media-Only Message

Idempotency

Channels

Message Routing

Polls

Method: `poll`

Error Handling

Example: Send with Media

Example: JavaScript Client

Message Format

Best Practices

Next Steps

Channels

Sessions

Agent Protocol

​Messages API

​Send Message

​Method: send

​Send Message with Media

​Single Media Attachment

​Multiple Media Attachments

​Media-Only Message

​Idempotency

​Channels

​Message Routing

​Polls

​Method: poll

​Error Handling

​Example: Send with Media

​Example: JavaScript Client

​Message Format

​Best Practices

​Next Steps

Channels

Sessions

Agent Protocol

Messages API

Send Message

Method: `send`

Send Message with Media

Single Media Attachment

Multiple Media Attachments

Media-Only Message

Idempotency

Channels

Message Routing

Polls

Method: `poll`

Error Handling

Example: Send with Media

Example: JavaScript Client

Message Format

Best Practices

Next Steps