Send a message

POST /v1/messages

The send action (1.60.0; channels.md section 2): one message to one recipient over one Connection through one of its send tools. In 1.60.0 every request is refused with capability_not_available and nothing is sent. From 1.61.0 (roadmap slice 2.15) the route checks the recipient's consent on the tool's channel for the Organization and for the Connection as sender, the rule of check_consent, and refuses an opted-out recipient with 422 contact_opted_out, one detail whose reason is a ConsentCheckReason, queuing nothing; otherwise it records the Message queued and hands it to the exec role as a leased action task, which checks the consent again before it sends (check_send_consent). Quiet hours defer a Message (deferred), never drop it. The Audit event names the Connection and the tool, never the recipient or the text.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the messages:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/messages" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "con_...",
    "tool": "<tool>",
    "to": "<to>",
    "body": "<body>"
  }'

const response = await fetch(`${process.env.VOCAL_API}/v1/messages`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "connection_id": "con_...",
    "tool": "<tool>",
    "to": "<to>",
    "body": "<body>"
  }),
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "connection_id": "con_...",
        "tool": "<tool>",
        "to": "<to>",
        "body": "<body>",
    },
)
print(response.status_code, response.text)

Parameters

Request body

Content type application/json, required: MessageCreateRequest.

Responses

Fields of the 201 answer

The shape is Message.