Sending messages

One endpoint sends every message, to a person or a conversation. Requires messages:write.

Send

POST /v1/messages
Authorization: Bearer wc_bot_live_…
Idempotency-Key: evt_88231:usr_9a1…
Content-Type: application/json

{
  "to": { "type": "user", "id": "usr_9a1…" },
  "text": "New lead: Sarah Chen (Acme Ltd) from Meta Lead Ads",
  "blocks": [ "…" ],
  "thread_id": null,
  "unfurl_links": false,
  "metadata": { "source": "leadey", "event": "lead.created", "lead_id": "lead_mul0oe5wo0dgol" }
}

curl -X POST https://public-api.workchats.com/v1/messages \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: evt_88231:usr_9a1d2c3e" \
  -d '{
    "to": { "type": "user", "id": "usr_9a1d2c3e-4b5f-4a6b-8c7d-9e0f1a2b3c4d" },
    "text": "New lead: Sarah Chen (Acme Ltd) from Meta Lead Ads"
  }'

const res = await fetch("https://public-api.workchats.com/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "evt_88231:usr_9a1d2c3e",
  },
  body: JSON.stringify({
    to: { type: "user", id: "usr_9a1d2c3e-4b5f-4a6b-8c7d-9e0f1a2b3c4d" },
    text: "New lead: Sarah Chen (Acme Ltd) from Meta Lead Ads",
  }),
});
const { message } = await res.json();

Field	Rule
`to.type` / `to.id`	`user` + `usr_…` for a DM, or `conversation` + `grp_…` / `chn_…` from `GET /v1/conversations`
`text`	Required, 1 to 4,000 characters. Shown to people, and it’s what push notifications use — always send it, even when you send `blocks`
`blocks`	Optional, at most 50, at most 16 KB total. See Blocks. Stored now, rendered in clients from a later phase
`thread_id`	Optional. A message id in the same destination — quoted above your new message, not a thread (Workchats has no threads). Anything else is `400 invalid_request`
`unfurl_links`	Accepted but has no effect yet: App messages never unfurl links
`metadata`	Optional object, at most 4 KB. Stored with the message, returned on later reads and (from Phase 1b) in the `interaction` callback. Not secret — anyone who can read the message can read it

Idempotency-Key is required on every send. See Idempotency before you write retry logic. Response 201:

{
  "ok": true,
  "message": {
    "id": "dmsg_4e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",
    "conversation_id": "dm_77a1b2c3-d4e5-4f60-8a7b-9c0d1e2f3a4b",
    "thread_id": null,
    "created_at": "2026-09-28T11:05:12Z"
  }
}

conversation_id is dm_… for a direct message, or the grp_… / chn_… you sent to. Keep it — you’ll want it for edits, and it’s what interaction callbacks reference in a later phase.

Edit

PATCH /v1/messages/{id}

Body is { "text": "…", "blocks": […], "metadata": {…} }. text is required. blocks replaces the stored blocks — leave it out to clear them. metadata, if present, is merged key-by-key into what’s already stored (it doesn’t replace it). to, thread_id and unfurl_links are ignored; you can’t move a message after sending it. You can only edit messages your own bot sent.

200

{ "ok": true, "message": { "id": "dmsg_4e2d1c0b-…", "conversation_id": "dm_77a1b2c3-…", "thread_id": null, "created_at": "2026-09-28T11:05:12Z" } }

Delete

DELETE /v1/messages/{id}

Returns 200 {"ok": true}, or 404 message_not_found if it’s already gone — treat both as success. This works even after your bot was removed from the conversation. Deletion removes the message’s content immediately from every client and API; see Data & security.

Errors specific to sending

HTTP	Code	Meaning
400	`missing_idempotency_key`	No `Idempotency-Key` header
400	`invalid_blocks`	A block failed validation — see Blocks
403	`cannot_dm_user`	The target can’t receive a DM from your bot
403	`not_in_conversation`	Your bot was removed from that group or channel
403	`not_allowed_in_conversation`	That channel is announcement-only
404	`conversation_not_found` / `user_not_found`	No such destination, or your bot was never a member
409	`conversation_archived` / `user_deactivated`	The destination can’t receive new messages
413	`payload_too_large`	Request body too large
415	`unsupported_media_type`	Body isn’t `application/json`
422	`idempotency_key_reused`	Same key, different body — or the original message was edited or deleted

Full table on Errors.

Getting Started

Guides

Reference

Changelog

Policies

Send

Edit

Delete

Errors specific to sending

​Send

​Edit

​Delete

​Errors specific to sending

Send

Edit

Delete

Errors specific to sending