API reference

Generated from the gateway's own OpenAPI 3.1 document, GET /v1/openapi.json, so it always matches the API. Every path starts at https://mcp.wagent.sh.

Errors and rate limits · Idempotency · Webhooks

Operations#

POST`/v1/agents/signup`#

An agent asks the owner of an email address for access, with no key. The owner gets an email and approves on the web with a WhatsApp code; the agent then claims its key once with claim_token. The answer is the same whatever happens to the email.

No keyIdempotency-Key required

Parameters
Name	In	Type	Required	Description
`Idempotency-Key`	header	string	Yes	A key you choose for this write, 1 to 255 visible ASCII characters. Repeating it never repeats the write.

Request body
Name	Type	Required
`owner_email`	string	Yes
`agent_name`	string	Yes
`scopes`	array of one of: read, draft_reply, transcribe, send_message	No
`note`	string	No

Responses202400409429503

Response 202
Name	Type	Required
`status`	always "pending_owner_approval"	Yes
`signup_id`	string	Yes
`claim_token`	string	Yes
`expires_at`	string (date-time)	Yes

Errors
Code	Status	Meaning
`invalid`	400	The request is not valid.
`idempotency_key_required`	400	Send an Idempotency-Key header (1 to 255 visible ASCII characters) with every write.
`already_requested`	409	This request was already made.
`rate_limited`	429	Too many requests. Retry after the time in Retry-After.
`unavailable`	503	Wagent could not complete this request, so nothing was done. Try again shortly.

GET`/v1/approvals`#

Items waiting for the owner in chats this agent may read, oldest first, each with its exact payload and sha256. CRM changes are not listed.

Any key

Responses200401403423429

Response 200
Name	Type	Required
`items[]`	array of object	Yes
`id`	string	Yes
`kind`	one of: draft, approval	Yes
`item_type`	one of: message, file, quote	Yes
`state`	one of: pending, failed	Yes
`chat_id`	string	Yes
`channel_id`	string or null	Yes
`agent_id`	string or null	Yes
`payload`	string or null	Yes
`sha256`	string or null	Yes
`created_at`	string (date-time)	Yes
`expires_at`	string (date-time) or null	Yes
`count`	integer	Yes

Errors
Code	Status	Meaning
`unauthorized`	401	The API key is missing, unknown, revoked or not valid for this workspace.
`ip_not_allowed`	403	This address is not on the agent's allowed addresses.
`agents_paused`	403	Agents are paused by the workspace owner.
`agent_off`	423	This agent is switched off by the workspace owner.
`rate_limited`	429	Too many requests. Retry after the time in Retry-After.

POST`/v1/approvals/{id}/approve`#

Approves an item by the sha256 of its payload; the stored payload is sent exactly as shown. Needs the owner's may-approve switch for this agent; never the agent's own items or a CRM change.

Needs a server keyIdempotency-Key required

Parameters
Name	In	Type	Required	Description
`Idempotency-Key`	header	string	Yes	A key you choose for this write, 1 to 255 visible ASCII characters. Repeating it never repeats the write.
`id`	path	string	Yes

Request body
Name	Type	Required	Description
`sha256`	string	Yes

Responses200400401403404409422423429

Response 200
Name	Type	Required
`status`	one of: sent, failed, unknown	Yes
`item`	object	Yes
`id`	string	Yes
`state`	string	Yes

Errors
Code	Status	Meaning
`invalid`	400	The request is not valid.
`idempotency_key_required`	400	Send an Idempotency-Key header (1 to 255 visible ASCII characters) with every write.
`unauthorized`	401	The API key is missing, unknown, revoked or not valid for this workspace.
`ip_not_allowed`	403	This address is not on the agent's allowed addresses.
`read_only_key`	403	This key is read only, so it cannot change anything.
`agents_paused`	403	Agents are paused by the workspace owner.
`approvals_off`	403	Approving through the API is off for this agent.
`own_item`	403	A key cannot approve its own agent's items.
`trial_limit`	403	This number reached its trial limit.
`not_found`	404	Not found.
`not_pending`	409	This item is no longer waiting.
`idempotency_in_progress`	409	A request with this Idempotency-Key is still running. Retry shortly.
`idempotency_key_mismatch`	422	This Idempotency-Key was already used with a different request.
`agent_off`	423	This agent is switched off by the workspace owner.
`rate_limited`	429	Too many requests. Retry after the time in Retry-After.

GET`/v1/chats`#

The chats this agent may read, newest activity first, each with what the agent can do there. Same as the MCP list_chats tool.

Any key

Parameters
Name	In	Type	Required
`limit`	query	integer	No
`cursor`	query	string	No
`q`	query	string	No

Responses200400401403423429503

Response 200
Name	Type	Required
`count`	integer	Yes
`next_cursor`	string or null	Yes
`wagent_data`	object	Yes
`untrusted`	always true	Yes
`note`	string	Yes
`items`	array of object	Yes

Errors
Code	Status	Meaning
`invalid`	400	The request is not valid.
`unauthorized`	401	The API key is missing, unknown, revoked or not valid for this workspace.
`ip_not_allowed`	403	This address is not on the agent's allowed addresses.
`agents_paused`	403	Agents are paused by the workspace owner.
`tool_off`	403	The workspace owner has not turned this tool on for this agent.
`agent_off`	423	This agent is switched off by the workspace owner.
`rate_limited`	429	Too many requests. Retry after the time in Retry-After.
`unavailable`	503	Wagent could not complete this request, so nothing was done. Try again shortly.

GET`/v1/chats/{id}/messages`#

One chat's messages: the newest page first, each page oldest first, with gap markers and the history window. Same as the MCP get_messages tool.

Any key

Parameters
Name	In	Type	Required
`id`	path	string	Yes
`limit`	query	integer	No
`cursor`	query	string	No

Responses200400401403404423429503

Response 200
Name	Type	Required
`chat_id`	string	Yes
`count`	integer	Yes
`next_cursor`	string or null	Yes
`wagent_data`	object	Yes
`untrusted`	always true	Yes
`note`	string	Yes
`items`	array of object	Yes

Errors
Code	Status	Meaning
`invalid`	400	The request is not valid.
`unauthorized`	401	The API key is missing, unknown, revoked or not valid for this workspace.
`ip_not_allowed`	403	This address is not on the agent's allowed addresses.
`agents_paused`	403	Agents are paused by the workspace owner.
`tool_off`	403	The workspace owner has not turned this tool on for this agent.
`not_found`	404	Not found.
`agent_off`	423	This agent is switched off by the workspace owner.
`rate_limited`	429	Too many requests. Retry after the time in Retry-After.
`unavailable`	503	Wagent could not complete this request, so nothing was done. Try again shortly.

POST`/v1/connect/sessions`#

A one-time connect session for one of your users, valid 15 minutes. Pass it to Wagent.connect() in your page; the number lands in this workspace tagged with `user`. Needs an active plan and a live key (a wg_test_ key gets 404). A repeat of the Idempotency-Key never returns a second session.

Needs a server keyIdempotency-Key required

Parameters
Name	In	Type	Required	Description
`Idempotency-Key`	header	string	Yes	A key you choose for this write, 1 to 255 visible ASCII characters. Repeating it never repeats the write.

Request body
Name	Type	Required	Description
`user`	string	Yes

Responses201400401403404409422429

Response 201
Name	Type	Required	Description
`session`	string	Yes
`expires_at`	string (date-time)	Yes

Errors
Code	Status	Meaning
`invalid`	400	The request is not valid.
`idempotency_key_required`	400	Send an Idempotency-Key header (1 to 255 visible ASCII characters) with every write.
`unauthorized`	401	The API key is missing, unknown, revoked or not valid for this workspace.
`ip_not_allowed`	403	This address is not on the agent's allowed addresses.
`read_only_key`	403	This key is read only, so it cannot change anything.
`not_found`	404	Not found.
`widget_unavailable`	409	This workspace cannot connect numbers through the widget until it has an active plan.
`idempotency_in_progress`	409	A request with this Idempotency-Key is still running. Retry shortly.
`already_requested`	409	This request was already made.
`idempotency_key_mismatch`	422	This Idempotency-Key was already used with a different request.
`rate_limited`	429	Too many requests. Retry after the time in Retry-After.

GET`/v1/events`#

Your webhook deliveries, newest first, 50 a page: event id, type, time, status, tries and the last answer's status and time taken. No payloads; replay an event to receive it again. status=not_delivered keeps pending, failed and skipped ones.

Any key

Parameters
Name	In	Type	Required	Description
`status`	query	one of: all, not_delivered	No
`cursor`	query	string	No

Responses200400401403423429

Response 200
Name	Type	Required
`events[]`	array of object	Yes
`id`	string	Yes
`type`	string	Yes
`created_at`	string (date-time)	Yes
`status`	one of: pending, sending, delivered, failed, skipped	Yes
`tries`	integer	Yes
`last_status`	integer or null	Yes
`last_latency_ms`	integer or null	Yes
`next_cursor`	string or null	Yes

Errors
Code	Status	Meaning
`invalid`	400	The request is not valid.
`unauthorized`	401	The API key is missing, unknown, revoked or not valid for this workspace.
`ip_not_allowed`	403	This address is not on the agent's allowed addresses.
`agents_paused`	403	Agents are paused by the workspace owner.
`agent_off`	423	This agent is switched off by the workspace owner.
`rate_limited`	429	Too many requests. Retry after the time in Retry-After.

POST`/v1/events/{id}/replay`#

Sends one event to your webhook URL again now, with the same webhook-id, and answers how that attempt went. It never repeats the action behind the event. At most 10 replays a minute.

Needs a server keyIdempotency-Key required

Parameters
Name	In	Type	Required	Description
`Idempotency-Key`	header	string	Yes	A key you choose for this write, 1 to 255 visible ASCII characters. Repeating it never repeats the write.
`id`	path	string	Yes

Responses200400401403404409422423429503

Response 200
Name	Type	Required
`status`	always "replayed"	Yes
`delivery`	object	Yes
`status`	one of: pending, sending, delivered, failed, skipped	Yes
`tries`	integer	Yes

Errors
Code	Status	Meaning
`idempotency_key_required`	400	Send an Idempotency-Key header (1 to 255 visible ASCII characters) with every write.
`unauthorized`	401	The API key is missing, unknown, revoked or not valid for this workspace.
`ip_not_allowed`	403	This address is not on the agent's allowed addresses.
`agents_paused`	403	Agents are paused by the workspace owner.
`read_only_key`	403	This key is read only, so it cannot change anything.
`not_found`	404	Not found.
`event_sending`	409	This event is being delivered right now. Retry in a few seconds.
`idempotency_in_progress`	409	A request with this Idempotency-Key is still running. Retry shortly.
`idempotency_key_mismatch`	422	This Idempotency-Key was already used with a different request.
`agent_off`	423	This agent is switched off by the workspace owner.
`rate_limited`	429	Too many requests. Retry after the time in Retry-After.
`unavailable`	503	Wagent could not complete this request, so nothing was done. Try again shortly.

GET`/v1/me`#

The key's workspace, agent, key and granted scopes.

Any key

Responses200401403429

Response 200
Name	Type	Required
`workspace`	object	Yes
`id`	string	Yes
`name`	string	Yes
`agent`	object	Yes
`id`	string	Yes
`name`	string	Yes
`kind`	string	Yes
`key`	object	Yes
`kind`	one of: server, read_only	Yes
`env`	one of: live, test	Yes
`last4`	string	Yes
`scopes`	array of string	Yes
`access_ends_at`	string (date-time) or null	Yes

Errors
Code	Status	Meaning
`unauthorized`	401	The API key is missing, unknown, revoked or not valid for this workspace.
`ip_not_allowed`	403	This address is not on the agent's allowed addresses.
`rate_limited`	429	Too many requests. Retry after the time in Retry-After.

POST`/v1/messages`#

Sends a WhatsApp text through the owner's rules: sent, waiting for the owner, or held. A retry after a crash that may have sent answers unknown and never sends again.

Needs a server keyIdempotency-Key required

Parameters
Name	In	Type	Required	Description
`Idempotency-Key`	header	string	Yes	A key you choose for this write, 1 to 255 visible ASCII characters. Repeating it never repeats the write.

Request body
Name	Type	Required
`chat_id`	string	Yes
`text`	string	Yes
`reply_to`	string	No

Responses200400401403404409422423429502503

Response 200
Name	Type	Required
`status`	one of: sent, waiting, held, unknown	Yes
`send_id`	string	No
`approval_id`	string	No
`draft_id`	string	No
`expires_at`	string	No
`note`	string	No
`reason`	string	No

Errors
Code	Status	Meaning
`invalid`	400	The request is not valid.
`idempotency_key_required`	400	Send an Idempotency-Key header (1 to 255 visible ASCII characters) with every write.
`unauthorized`	401	The API key is missing, unknown, revoked or not valid for this workspace.
`ip_not_allowed`	403	This address is not on the agent's allowed addresses.
`read_only_key`	403	This key is read only, so it cannot change anything.
`agents_paused`	403	Agents are paused by the workspace owner.
`tool_off`	403	The workspace owner has not turned this tool on for this agent.
`blocked`	403	The owner's rules do not allow this.
`not_found`	404	Not found.
`idempotency_in_progress`	409	A request with this Idempotency-Key is still running. Retry shortly.
`idempotency_key_mismatch`	422	This Idempotency-Key was already used with a different request.
`agent_off`	423	This agent is switched off by the workspace owner.
`rate_limited`	429	Too many requests. Retry after the time in Retry-After.
`send_failed`	502	WhatsApp did not accept the message. Nothing was delivered.
`unavailable`	503	Wagent could not complete this request, so nothing was done. Try again shortly.

GET`/v1/openapi.json`#

This document: OpenAPI 3.1, generated from the code that serves the API. No key needed.

No key

Responses200

Response 200
Name	Type	Required	Description
`openapi`	always "3.1.0"	Yes

POST`/v1/pause`#

Pauses every agent in the workspace at once and tells owners and admins. A second call keeps the first time. Only an owner or admin can resume, on the web.

Needs a server keyIdempotency-Key required

Parameters
Name	In	Type	Required	Description
`Idempotency-Key`	header	string	Yes	A key you choose for this write, 1 to 255 visible ASCII characters. Repeating it never repeats the write.

Responses200400401403409422429

Response 200
Name	Type	Required	Description
`paused`	always true	Yes
`at`	string (date-time)	Yes

Errors
Code	Status	Meaning
`idempotency_key_required`	400	Send an Idempotency-Key header (1 to 255 visible ASCII characters) with every write.
`unauthorized`	401	The API key is missing, unknown, revoked or not valid for this workspace.
`ip_not_allowed`	403	This address is not on the agent's allowed addresses.
`read_only_key`	403	This key is read only, so it cannot change anything.
`idempotency_in_progress`	409	A request with this Idempotency-Key is still running. Retry shortly.
`idempotency_key_mismatch`	422	This Idempotency-Key was already used with a different request.
`rate_limited`	429	Too many requests. Retry after the time in Retry-After.

POST`/v1/sandbox/inbound`#

Sandbox only (a wg_test_ key): a message from test contact 1 to 5 to the sandbox number. It arrives like a real message, through the inbox, the rules, Activity and your webhooks. 60 a minute per sandbox.

Needs a server keyIdempotency-Key required

Parameters
Name	In	Type	Required	Description
`Idempotency-Key`	header	string	Yes	A key you choose for this write, 1 to 255 visible ASCII characters. Repeating it never repeats the write.

Request body
Name	Type	Required	Description
`contact`	integer	Yes
`text`	string	Yes

Responses202400401403404409422429

Response 202
Name	Type	Required	Description
`message_id`	string	Yes

Errors
Code	Status	Meaning
`invalid`	400	The request is not valid.
`idempotency_key_required`	400	Send an Idempotency-Key header (1 to 255 visible ASCII characters) with every write.
`unauthorized`	401	The API key is missing, unknown, revoked or not valid for this workspace.
`ip_not_allowed`	403	This address is not on the agent's allowed addresses.
`read_only_key`	403	This key is read only, so it cannot change anything.
`not_found`	404	Not found.
`idempotency_in_progress`	409	A request with this Idempotency-Key is still running. Retry shortly.
`idempotency_key_mismatch`	422	This Idempotency-Key was already used with a different request.
`rate_limited`	429	Too many requests. Retry after the time in Retry-After.

POST`/v1/sandbox/session`#

Sandbox only (a wg_test_ key): moves the sandbox number to one of the six session states. Each change sends the same session events a real number would.

Needs a server keyIdempotency-Key required

Parameters
Name	In	Type	Required	Description
`Idempotency-Key`	header	string	Yes	A key you choose for this write, 1 to 255 visible ASCII characters. Repeating it never repeats the write.

Request body
Name	Type	Required	Description
`state`	one of: not_started, starting, qr, authorized, error, sync_error	Yes

Responses200400401403404409422429

Response 200
Name	Type	Required	Description
`state`	one of: not_started, starting, qr, authorized, error, sync_error	Yes

Errors
Code	Status	Meaning
`invalid`	400	The request is not valid.
`idempotency_key_required`	400	Send an Idempotency-Key header (1 to 255 visible ASCII characters) with every write.
`unauthorized`	401	The API key is missing, unknown, revoked or not valid for this workspace.
`ip_not_allowed`	403	This address is not on the agent's allowed addresses.
`read_only_key`	403	This key is read only, so it cannot change anything.
`not_found`	404	Not found.
`idempotency_in_progress`	409	A request with this Idempotency-Key is still running. Retry shortly.
`idempotency_key_mismatch`	422	This Idempotency-Key was already used with a different request.
`rate_limited`	429	Too many requests. Retry after the time in Retry-After.

GET`/v1/sessions`#

Every WhatsApp number of this workspace that is not released, oldest first: its state (one of six), status, history sync progress from 0 to 100, and the user reference you passed when your user connected it through the widget.

Any key

Responses200401403423429

Response 200
Name	Type	Required
`sessions[]`	array of object	Yes
`id`	string (uuid)	Yes
`phone_number`	string or null	Yes
`state`	one of: not_started, starting, qr, authorized, error, sync_error	Yes
`status`	one of: connected, syncing, logged_out, banned, not_yet	Yes
`sync_progress`	integer or null	Yes
`external_ref`	string or null	Yes
`connected_at`	string (date-time) or null	Yes

Errors
Code	Status	Meaning
`unauthorized`	401	The API key is missing, unknown, revoked or not valid for this workspace.
`ip_not_allowed`	403	This address is not on the agent's allowed addresses.
`agents_paused`	403	Agents are paused by the workspace owner.
`agent_off`	423	This agent is switched off by the workspace owner.
`rate_limited`	429	Too many requests. Retry after the time in Retry-After.

Webhooks#

Each event arrives as a signed POST with the envelope below. See Webhooks and verifying signatures.

Event`message.received`#

Family: messages

A message arrived in a chat the agent can read.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "message.received"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`message_id`	string (uuid)	Yes
`chat_id`	string (uuid)	Yes
`channel_id`	string (uuid)	Yes
`wagent_data`	object	Yes
`untrusted`	always true	Yes
`note`	string	Yes
`items[]`	array of object	Yes
`source`	object, fields not shown	Yes
`text`	string	Yes
`redacted`	object	No
`meta`	object, fields not shown	Yes

Event`message.status`#

Family: messages

A sent message was delivered or read.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "message.status"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`message_id`	string (uuid)	Yes
`chat_id`	string (uuid)	Yes
`channel_id`	string (uuid)	Yes
`status`	one of: pending, sent, delivered, read, played, failed, deleted	Yes

Event`message.sent`#

Family: messages

A message was sent from the number.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "message.sent"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`message_id`	string (uuid)	Yes
`chat_id`	string (uuid)	Yes
`channel_id`	string (uuid)	Yes

Event`message.edited`#

Family: messages

A message was edited.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "message.edited"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`message_id`	string (uuid)	Yes
`chat_id`	string (uuid)	Yes
`channel_id`	string (uuid)	Yes
`wagent_data`	object	Yes
`untrusted`	always true	Yes
`note`	string	Yes
`items[]`	array of object	Yes
`source`	object, fields not shown	Yes
`text`	string	Yes
`redacted`	object	No
`meta`	object, fields not shown	Yes

Event`message.deleted`#

Family: messages

A message was deleted.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "message.deleted"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`message_id`	string (uuid)	Yes
`chat_id`	string (uuid)	Yes
`channel_id`	string (uuid)	Yes

Event`status.posted`#

Family: statuses

A contact posted a status (story).

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "status.posted"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`message_id`	string (uuid)	Yes
`chat_id`	string (uuid)	Yes
`channel_id`	string (uuid)	Yes
`type`	string	Yes

Event`chat.updated`#

Family: chats

A chat was archived, muted or pinned, or changed otherwise.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "chat.updated"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`chat_id`	string (uuid)	Yes
`channel_id`	string (uuid)	Yes
`removed`	boolean	Yes

Event`contact.updated`#

Family: contacts

A contact was added or renamed.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "contact.updated"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`chat_id`	string (uuid)	Yes
`channel_id`	string (uuid)	Yes

Event`group.updated`#

Family: groups

A group's members or settings changed.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "group.updated"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`chat_id`	string (uuid)	Yes
`channel_id`	string (uuid)	Yes
`change`	one of: updated, add, remove, promote, demote, leave	Yes
`count`	integer or null	Yes

Event`label.updated`#

Family: labels

A label was added to or removed from a chat.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "label.updated"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`label_id`	string	Yes
`channel_id`	string (uuid)	Yes
`removed`	boolean	Yes

Event`presence.updated`#

Family: presences

A contact started typing or came online.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "presence.updated"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`chat_id`	string (uuid)	Yes
`channel_id`	string (uuid)	Yes
`presence`	one of: online, offline, typing, recording	Yes

Event`call.received`#

Family: calls

A call came in.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "call.received"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`chat_id`	string (uuid)	Yes
`channel_id`	string (uuid)	Yes
`call_id`	string	Yes
`status`	one of: initiated, ringing, missed, answered	Yes
`video`	boolean	Yes
`group`	boolean	Yes

Event`draft.created`#

Always sent

An agent wrote a draft for the owner to review.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "draft.created"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`approval_id`	string (uuid)	Yes
`agent_id`	string (uuid) or null	Yes
`chat_id`	string (uuid)	Yes
`channel_id`	string (uuid) or null	Yes
`kind`	one of: draft, approval	Yes
`item_type`	string	Yes
`reason`	string	Yes
`expires_at`	string (date-time) or null	Yes
`created_at`	string (date-time)	Yes

Event`approval.requested`#

Always sent

An agent's action is waiting for the owner's approval.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "approval.requested"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`approval_id`	string (uuid)	Yes
`agent_id`	string (uuid) or null	Yes
`chat_id`	string (uuid)	Yes
`channel_id`	string (uuid) or null	Yes
`kind`	one of: draft, approval	Yes
`item_type`	string	Yes
`reason`	string	Yes
`expires_at`	string (date-time) or null	Yes
`created_at`	string (date-time)	Yes

Event`approval.decided`#

Always sent

The owner approved or declined a waiting item.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "approval.decided"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`approval_id`	string (uuid)	Yes
`attempt`	integer or null	Yes
`agent_id`	string (uuid) or null	Yes
`chat_id`	string (uuid)	Yes
`channel_id`	string (uuid) or null	Yes
`result`	one of: approved, skipped, expired, taken_over	Yes
`via`	one of: web, phone, api or null	Yes
`item_type`	string or null	Yes
`actor_kind`	one of: agent, member, system, phone	Yes

Event`rule.changed`#

Always sent

The owner changed an agent's rights or a workspace rule.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "rule.changed"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`agent_id`	string (uuid) or null	Yes
`field`	string or null	Yes

Event`agent.paused`#

Always sent

An agent, or every agent, was paused.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "agent.paused"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`agent_id`	string (uuid) or null	Yes
`all`	boolean	Yes
`via`	string or null	No

Event`agent.revoked`#

Always sent

An agent's access was removed.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "agent.revoked"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`agent_id`	string (uuid)	Yes

Event`session.state`#

Family: channel

The number's connection state changed.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "session.state"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`session`	object	Yes
`id`	string (uuid)	Yes
`phone_number`	string or null	Yes
`state`	one of: not_started, starting, qr, authorized, error, sync_error	Yes
`status`	one of: connected, syncing, logged_out, banned, not_yet	Yes
`external_ref`	string or null	Yes
`from`	one of: not_started, starting, qr, authorized, error, sync_error	Yes
`to`	one of: not_started, starting, qr, authorized, error, sync_error	Yes

Event`session.syncing`#

Family: channel

Chat sync started or moved on.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "session.syncing"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`session`	object	Yes
`id`	string (uuid)	Yes
`phone_number`	string or null	Yes
`state`	one of: not_started, starting, qr, authorized, error, sync_error	Yes
`status`	one of: connected, syncing, logged_out, banned, not_yet	Yes
`external_ref`	string or null	Yes

Event`session.banned`#

Family: channel

WhatsApp banned the number.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "session.banned"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`session`	object	Yes
`id`	string (uuid)	Yes
`phone_number`	string or null	Yes
`state`	one of: not_started, starting, qr, authorized, error, sync_error	Yes
`status`	one of: connected, syncing, logged_out, banned, not_yet	Yes
`external_ref`	string or null	Yes

Event`session.connected`#

Family: users

The number signed in.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "session.connected"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`session`	object	Yes
`id`	string (uuid)	Yes
`phone_number`	string or null	Yes
`state`	one of: not_started, starting, qr, authorized, error, sync_error	Yes
`status`	one of: connected, syncing, logged_out, banned, not_yet	Yes
`external_ref`	string or null	Yes
`from`	one of: not_started, starting, qr, authorized, error, sync_error	Yes
`to`	one of: not_started, starting, qr, authorized, error, sync_error	Yes

Event`session.logged_out`#

Family: users

The number signed out.

Payload
Name	Type	Required
`id`	string	Yes
`type`	always "session.logged_out"	Yes
`created_at`	string (date-time)	Yes
`workspace_id`	string (uuid)	Yes
`env`	one of: live, test	Yes
`data`	object	Yes
`session`	object	Yes
`id`	string (uuid)	Yes
`phone_number`	string or null	Yes
`state`	one of: not_started, starting, qr, authorized, error, sync_error	Yes
`status`	one of: connected, syncing, logged_out, banned, not_yet	Yes
`external_ref`	string or null	Yes
`from`	one of: not_started, starting, qr, authorized, error, sync_error	Yes
`to`	one of: not_started, starting, qr, authorized, error, sync_error	Yes

API reference

Operations#

POST/v1/agents/signup#

GET/v1/approvals#

POST/v1/approvals/{id}/approve#

GET/v1/chats#

GET/v1/chats/{id}/messages#

POST/v1/connect/sessions#

GET/v1/events#

POST/v1/events/{id}/replay#

GET/v1/me#

POST/v1/messages#

GET/v1/openapi.json#

POST/v1/pause#

POST/v1/sandbox/inbound#

POST/v1/sandbox/session#

GET/v1/sessions#

Webhooks#

Eventmessage.received#

Eventmessage.status#

Eventmessage.sent#

Eventmessage.edited#

Eventmessage.deleted#

Eventstatus.posted#

Eventchat.updated#

Eventcontact.updated#

Eventgroup.updated#

Eventlabel.updated#

Eventpresence.updated#

Eventcall.received#

Eventdraft.created#

Eventapproval.requested#

Eventapproval.decided#

Eventrule.changed#

Eventagent.paused#

Eventagent.revoked#

Eventsession.state#

Eventsession.syncing#

Eventsession.banned#

Eventsession.connected#

Eventsession.logged_out#

POST`/v1/agents/signup`#

GET`/v1/approvals`#

POST`/v1/approvals/{id}/approve`#

GET`/v1/chats`#

GET`/v1/chats/{id}/messages`#

POST`/v1/connect/sessions`#

GET`/v1/events`#

POST`/v1/events/{id}/replay`#

GET`/v1/me`#

POST`/v1/messages`#

GET`/v1/openapi.json`#

POST`/v1/pause`#

POST`/v1/sandbox/inbound`#

POST`/v1/sandbox/session`#

GET`/v1/sessions`#

Event`message.received`#

Event`message.status`#

Event`message.sent`#

Event`message.edited`#

Event`message.deleted`#

Event`status.posted`#

Event`chat.updated`#

Event`contact.updated`#

Event`group.updated`#

Event`label.updated`#

Event`presence.updated`#

Event`call.received`#

Event`draft.created`#

Event`approval.requested`#

Event`approval.decided`#

Event`rule.changed`#

Event`agent.paused`#

Event`agent.revoked`#

Event`session.state`#

Event`session.syncing`#

Event`session.banned`#

Event`session.connected`#

Event`session.logged_out`#