WhatsApp: Voiceland AI API reference

The WhatsApp endpoints of the Voiceland AI API, with parameters, schemas and curl examples.

Last updated: 2026-10-20

GET `/v1/contacts/{id}/whatsapp`#

List a contact's WhatsApp conversations. The conversations linked to the contact on any of your numbers, newest message first. With WhatsApp off the list is empty.

Parameters

Name	In	Type	Required	Description
`id`	`path`	string	Yes	Contact id.
`limit`	`query`	integer		At most this many, 1 to 200 (default 50); larger values are capped.

Responses

Code	Description
`200`	Success.
`400`	`limit` is not a whole number (`invalid_request`).
`401`	Missing or invalid API key.
`404`	Your project has no contact with this id (`not_found`).
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/contacts/{id}/whatsapp" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppContactConversationList.

GET `/v1/integrations/whatsapp/config`#

Read the WhatsApp settings of this deployment. Whether WhatsApp is enabled here, whether your plan includes it, the limits every setting is checked against and the default AI disclosure lines. With WhatsApp off the answer is {"enabled": false} and nothing else, and every other WhatsApp route answers 404 whatsapp_unconfigured. Never gated.

Parameters

Name	In	Type	Required	Description
`origin`	`query`	string		The console origin asking (`window.location.origin`). `allowed_origins` is then that origin when Meta's connection window may run on it, and empty when it may not. Without it (and without an `Origin` header) `allowed_origins` is the deployment's own console only.

Responses

Code	Description
`200`	Success.
`401`	Missing or invalid API key.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/integrations/whatsapp/config" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppConfigView.

GET `/v1/integrations/whatsapp/conversations`#

List a number's conversations. Newest message first, each with its status. state is evaluated when you read (a status changes with time), over at most five store pages per request: a filtered page may hold fewer than limit items while next_cursor is not empty. No summaries in the list. **Paging.** Pass next_cursor back as ?cursor=. **An empty next_cursor is the only signal that you have seen everything**; a cursor this listing did not issue answers 400 invalid_cursor.

Parameters

Name	In	Type	Description
`number`	`query`	string	The number's phone number id. Required when the project has more than one number; with one, it is that one.
`state`	`query`	string	`all` (default) or one status state: `agent_answering`, `agent_waiting`, `paused`, `people_only`, `agent_off`, `window_closed` or `not_live`.
`limit`	`query`	integer	Items per page, 1 to 100 (default 50); larger values are capped.
`cursor`	`query`	string	The `next_cursor` of the previous page. Omit for the first page.

Responses

Code	Description
`200`	Success.
`400`	The project has several numbers and `number` names none (`whatsapp_number_required`), `state` is not a state (`whatsapp_invalid_state`), `limit` is not a whole number (`invalid_request`), or the cursor was not issued by this listing (`invalid_cursor`).
`401`	Missing or invalid API key.
`404`	Your project has no connected number with this id (`whatsapp_number_not_found`); an id of the wrong shape answers the same.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/integrations/whatsapp/conversations" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppConversationPage.

GET `/v1/integrations/whatsapp/conversations/{conversation_id}`#

Read one conversation. The conversation with its status and the agent's summary of it.

Parameters

Name	In	Type	Required	Description
`conversation_id`	`path`	string	Yes	Conversation id: `wc` and 16 letters or digits.

Responses

Code	Description
`200`	Success.
`401`	Missing or invalid API key.
`404`	Your project has no conversation with this id (`whatsapp_conversation_not_found`), or it is being erased.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/integrations/whatsapp/conversations/{conversation_id}" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppConversationView.

POST `/v1/integrations/whatsapp/conversations/{conversation_id}/claim`#

Take a conversation over. A person is handling it: the agent pauses while the claim is open. No body.

Parameters

Name	In	Type	Required	Description
`conversation_id`	`path`	string	Yes	Conversation id: `wc` and 16 letters or digits.

Request body

application/json Schema: WhatsAppEmptyRequest

Field	Type	Required	Description

Responses

Code	Description
`200`	Success.
`401`	Missing or invalid API key.
`402`	Your plan does not include WhatsApp (`feature_not_entitled`, with `missing_features: ["whatsapp_channel"]`), or the project has no plan (`no_subscription`). Nothing was changed.
`403`	This deployment records a named person for every human-oversight action and the request carries none (`actor_identity_required`): send it through the console. An API key cannot be named, so it is refused while that rule is on.
`404`	Your project has no conversation with this id (`whatsapp_conversation_not_found`), or it is being erased.
`409`	The conversation changed too often while this was applied (`whatsapp_conversation_busy`); try again.
`413`	The body is larger than 1 KiB (`body_too_large`).
`422`	The body is JSON this route cannot read (`invalid_request`): a field the document does not have, at any depth, a value of the wrong type, or more than one JSON value.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl -X POST "https://api.voiceland.ai/v1/integrations/whatsapp/conversations/{conversation_id}/claim" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppConversationView.

GET `/v1/integrations/whatsapp/conversations/{conversation_id}/media/{media_id}`#

Download a message's media. The stored file of a message, as an attachment. Its Content-Type is the file's type when that is an image, audio, video, PDF, office or plain-text type, else application/octet-stream; a message's media.download_path names this route while the file is stored.

Parameters

Name	In	Type	Required	Description
`conversation_id`	`path`	string	Yes	Conversation id: `wc` and 16 letters or digits.
`media_id`	`path`	string	Yes	Media id: `wm` and 16 hex digits, a message's `media.id`.

Responses

Code	Description
`200`	Success.
`401`	Missing or invalid API key.
`404`	Your project has no conversation with this id (`whatsapp_conversation_not_found`), or it is being erased. Or the file is not stored: not downloaded, removed by retention, or archived (`whatsapp_media_not_found`); the message's `media.state` says which.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/integrations/whatsapp/conversations/{conversation_id}/media/{media_id}" \
  -H "Authorization: Bearer VL_API_KEY"

GET `/v1/integrations/whatsapp/conversations/{conversation_id}/messages`#

List a conversation's messages. Newest first, every message kept under your retention, from the customer, the agent, your people and your operations boards. **Paging.** Pass next_cursor back as ?cursor=. **An empty next_cursor is the only signal that you have seen everything**; a cursor this listing did not issue answers 400 invalid_cursor.

Parameters

Name	In	Type	Required	Description
`conversation_id`	`path`	string	Yes	Conversation id: `wc` and 16 letters or digits.
`limit`	`query`	integer		Items per page, 1 to 200 (default 50); larger values are capped.
`cursor`	`query`	string		The `next_cursor` of the previous page. Omit for the first page.

Responses

Code	Description
`200`	Success.
`400`	`limit` is not a whole number (`invalid_request`), or the cursor was not issued by this listing (`invalid_cursor`).
`401`	Missing or invalid API key.
`404`	Your project has no conversation with this id (`whatsapp_conversation_not_found`), or it is being erased.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/integrations/whatsapp/conversations/{conversation_id}/messages" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppMessagePage.

POST `/v1/integrations/whatsapp/conversations/{conversation_id}/messages`#

Reply in a conversation. Sends a text to the customer as your team, inside the 24-hour window that the customer's last message opened. The reply pauses the agent as the policy's console trigger says. 60 a minute per project. When Meta took the request and gave no answer, the reply may have been sent: 202 with status: unknown, and the message appears in the conversation if Meta confirms it; do not send it again.

Parameters

Name	In	Type	Required	Description
`conversation_id`	`path`	string	Yes	Conversation id: `wc` and 16 letters or digits.

Request body

application/json Schema: WhatsAppReplyRequest

Field	Type	Required	Description
`rep_name`	string		The name the conversation shows for the reply, at most 80 characters.
`text`	string	Yes	1 to 4,096 characters.

Responses

Code	Description
`201`	Sent.
`202`	Meta did not confirm the send: it may have been sent.
`400`	`text` is blank (`whatsapp_text_required`) or longer than 4,096 characters (`whatsapp_text_too_long`), or `rep_name` is longer than 80 (`invalid_request`).
`401`	Missing or invalid API key.
`402`	Your plan does not include WhatsApp (`feature_not_entitled`, with `missing_features: ["whatsapp_channel"]`), or the project has no plan (`no_subscription`). Nothing was changed.
`403`	This deployment records a named person for every human-oversight action and the request carries none (`actor_identity_required`): send it through the console. An API key cannot be named, so it is refused while that rule is on.
`404`	Your project has no conversation with this id (`whatsapp_conversation_not_found`), or it is being erased.
`409`	The 24-hour window is closed (`whatsapp_window_closed`: send a template from an operations board), the number is not live (`whatsapp_number_not_live`), or its token no longer works (`whatsapp_token_invalid`). The conversation changed too often while the reply was claimed (`whatsapp_conversation_busy`, with `Retry-After`): try again.
`413`	The body is larger than 20 KiB (`body_too_large`).
`422`	The body is JSON this route cannot read (`invalid_request`): a field the document does not have, at any depth, a value of the wrong type, or more than one JSON value.
`429`	Too many replies from your project (`whatsapp_rate_limited`). Meta's own throttling answers the same code with `meta_code` set.
`4XX`	Request error (validation, not-found, etc.).
`502`	Meta refused the request (`whatsapp_meta_error`, with `meta_code`); Meta's own text is not passed on.
`5XX`	Server or upstream error.

Example request

curl -X POST "https://api.voiceland.ai/v1/integrations/whatsapp/conversations/{conversation_id}/messages" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rep_name": "Anna",
  "text": "Your order ships today."
}'

A successful response returns a WhatsAppReplyView.

POST `/v1/integrations/whatsapp/conversations/{conversation_id}/pause`#

Pause the agent in a conversation. A hand pause: the agent does not answer here until the duration ends or someone lets it answer again. It replaces any earlier hand action and outlasts the policy's own pauses. quiet_minutes ends once the conversation is quiet that long.

Parameters

Name	In	Type	Required	Description
`conversation_id`	`path`	string	Yes	Conversation id: `wc` and 16 letters or digits.

Request body

application/json Schema: WhatsAppPauseRequest

Field	Type	Required	Description
`duration`	`WhatsAppDuration`	Yes	How long: `minutes`, `end_of_day`, `window_end`, `quiet_minutes` or `manual`.

Responses

Code	Description
`200`	Success.
`400`	The duration is not one this action takes, or is out of its bounds (`whatsapp_duration_invalid`, with `details[]` naming the bound).
`401`	Missing or invalid API key.
`402`	Your plan does not include WhatsApp (`feature_not_entitled`, with `missing_features: ["whatsapp_channel"]`), or the project has no plan (`no_subscription`). Nothing was changed.
`403`	This deployment records a named person for every human-oversight action and the request carries none (`actor_identity_required`): send it through the console. An API key cannot be named, so it is refused while that rule is on.
`404`	Your project has no conversation with this id (`whatsapp_conversation_not_found`), or it is being erased.
`409`	The conversation changed too often while this was applied (`whatsapp_conversation_busy`); try again.
`413`	The body is larger than 1 KiB (`body_too_large`).
`422`	The body is JSON this route cannot read (`invalid_request`): a field the document does not have, at any depth, a value of the wrong type, or more than one JSON value.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl -X POST "https://api.voiceland.ai/v1/integrations/whatsapp/conversations/{conversation_id}/pause" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "duration": {
    "kind": "minutes",
    "minutes": 60
  }
}'

A successful response returns a WhatsAppConversationView.

POST `/v1/integrations/whatsapp/conversations/{conversation_id}/release`#

Hand a conversation back. Ends a claim; the policy's console pause runs from now. No body.

Parameters

Name	In	Type	Required	Description
`conversation_id`	`path`	string	Yes	Conversation id: `wc` and 16 letters or digits.

Request body

application/json Schema: WhatsAppEmptyRequest

Field	Type	Required	Description

Responses

Code	Description
`200`	Success.
`401`	Missing or invalid API key.
`402`	Your plan does not include WhatsApp (`feature_not_entitled`, with `missing_features: ["whatsapp_channel"]`), or the project has no plan (`no_subscription`). Nothing was changed.
`403`	This deployment records a named person for every human-oversight action and the request carries none (`actor_identity_required`): send it through the console. An API key cannot be named, so it is refused while that rule is on.
`404`	Your project has no conversation with this id (`whatsapp_conversation_not_found`), or it is being erased.
`409`	The conversation changed too often while this was applied (`whatsapp_conversation_busy`); try again.
`413`	The body is larger than 1 KiB (`body_too_large`).
`422`	The body is JSON this route cannot read (`invalid_request`): a field the document does not have, at any depth, a value of the wrong type, or more than one JSON value.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl -X POST "https://api.voiceland.ai/v1/integrations/whatsapp/conversations/{conversation_id}/release" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppConversationView.

POST `/v1/integrations/whatsapp/conversations/{conversation_id}/resume`#

Let the agent answer in a conversation again. Ends a pause. With hold, the agent keeps answering here until the hold ends, whatever the policy's pauses say; without one, the policy decides from here.

Parameters

Name	In	Type	Required	Description
`conversation_id`	`path`	string	Yes	Conversation id: `wc` and 16 letters or digits.

Request body

application/json Schema: WhatsAppResumeRequest

Field	Type	Required	Description
`hold`	`WhatsAppDuration`		Keep the agent answering until then: `minutes`, `end_of_day`, `window_end` or `manual`.

Responses

Code	Description
`200`	Success.
`400`	The duration is not one this action takes, or is out of its bounds (`whatsapp_duration_invalid`, with `details[]` naming the bound).
`401`	Missing or invalid API key.
`402`	Your plan does not include WhatsApp (`feature_not_entitled`, with `missing_features: ["whatsapp_channel"]`), or the project has no plan (`no_subscription`). Nothing was changed.
`403`	This deployment records a named person for every human-oversight action and the request carries none (`actor_identity_required`): send it through the console. An API key cannot be named, so it is refused while that rule is on.
`404`	Your project has no conversation with this id (`whatsapp_conversation_not_found`), or it is being erased.
`409`	The conversation changed too often while this was applied (`whatsapp_conversation_busy`); try again.
`413`	The body is larger than 1 KiB (`body_too_large`).
`422`	The body is JSON this route cannot read (`invalid_request`): a field the document does not have, at any depth, a value of the wrong type, or more than one JSON value.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl -X POST "https://api.voiceland.ai/v1/integrations/whatsapp/conversations/{conversation_id}/resume" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "hold": {
    "kind": "end_of_day"
  }
}'

A successful response returns a WhatsAppConversationView.

DELETE `/v1/integrations/whatsapp/conversations/{conversation_id}/summary`#

Forget the agent's summary of a conversation. The agent starts its next session here without the summary of the earlier ones. Never gated.

Parameters

Name	In	Type	Required	Description
`conversation_id`	`path`	string	Yes	Conversation id: `wc` and 16 letters or digits.

Responses

Code	Description
`204`	Forgotten; the messages stay.
`401`	Missing or invalid API key.
`404`	Your project has no conversation with this id (`whatsapp_conversation_not_found`), or it is being erased.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl -X DELETE "https://api.voiceland.ai/v1/integrations/whatsapp/conversations/{conversation_id}/summary" \
  -H "Authorization: Bearer VL_API_KEY"

GET `/v1/integrations/whatsapp/numbers`#

List your connected numbers. Every number connected to this project, oldest connection first; not paged (a project has a few). Never a token: token says only when it expires and whether it still works. Numbers are connected in the console, through Meta's connection window; the API has no connect route.

Responses

Code	Description
`200`	Success.
`401`	Missing or invalid API key.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/integrations/whatsapp/numbers" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppNumberList.

DELETE `/v1/integrations/whatsapp/numbers/{phone_number_id}`#

Disconnect a number. Stops routing at once and ends the number's live sessions. The conversations stay under their retention. When this was the WhatsApp account's last number here, the account's subscription and its token are released too; unsubscribed and token_deleted say whether that finished already. Never gated: a project whose plan changed can still remove what it has.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	`path`	string	Yes	Meta's phone number id of one of your connected numbers.

Responses

Code	Description
`200`	Success.
`401`	Missing or invalid API key.
`404`	Your project has no connected number with this id (`whatsapp_number_not_found`); an id of the wrong shape answers the same.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl -X DELETE "https://api.voiceland.ai/v1/integrations/whatsapp/numbers/{phone_number_id}" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppDisconnectView.

GET `/v1/integrations/whatsapp/numbers/{phone_number_id}`#

Read one number. The number with the operations boards whose WhatsApp trigger listens to it (boards).

Parameters

Name	In	Type	Required	Description
`phone_number_id`	`path`	string	Yes	Meta's phone number id of one of your connected numbers.

Responses

Code	Description
`200`	Success.
`401`	Missing or invalid API key.
`404`	Your project has no connected number with this id (`whatsapp_number_not_found`); an id of the wrong shape answers the same.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/integrations/whatsapp/numbers/{phone_number_id}" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppNumberView.

PATCH `/v1/integrations/whatsapp/numbers/{phone_number_id}`#

Change a number's settings. Every key is optional and only the keys you send change; memory and disclosure_line are whole blocks. Send version (the number's) to refuse the change if someone else changed the number since you read it. Changing agent ends the conversation's live session, and "" leaves the number to your people. Under the pseudonymize_at_rest transcript policy a summary switched on is stored and reported off (pseudonymized: true).

Parameters

Name	In	Type	Required	Description
`phone_number_id`	`path`	string	Yes	Meta's phone number id of one of your connected numbers.

Request body

application/json Schema: WhatsAppNumberPatch

Field	Type	Required	Description
`agent`	string
`create_contact_on_first_message`	boolean
`disclosure_line`	`WhatsAppLinePatch`
`memory`	`WhatsAppMemoryPatch`
`notify_emails`	array of string
`timezone`	string
`version`	integer

Responses

Code	Description
`200`	Success.
`400`	A setting is out of bounds (`whatsapp_invalid_settings`, with `details[]`), or `agent` names no agent of the project (`whatsapp_agent_not_found`).
`401`	Missing or invalid API key.
`402`	Your plan does not include WhatsApp (`feature_not_entitled`, with `missing_features: ["whatsapp_channel"]`), or the project has no plan (`no_subscription`). Nothing was changed.
`403`	Only your provider (Voiceland) switches the AI disclosure line off (`operator_only_field`); its texts stay editable.
`404`	Your project has no connected number with this id (`whatsapp_number_not_found`); an id of the wrong shape answers the same.
`409`	`version` is not the number's version (`whatsapp_version_conflict`): read it again.
`413`	The body is larger than 16 KiB (`body_too_large`).
`422`	The body is JSON this route cannot read (`invalid_request`): a field the document does not have, at any depth, a value of the wrong type, or more than one JSON value.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl -X PATCH "https://api.voiceland.ai/v1/integrations/whatsapp/numbers/{phone_number_id}" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent": "reception",
  "memory": {
    "idle_close_min": 15,
    "lookback_days": 90,
    "recent_messages": 20,
    "summary_enabled": true
  },
  "notify_emails": [
    "ops@acme.example"
  ],
  "timezone": "Europe/Athens",
  "version": 12
}'

A successful response returns a WhatsAppNumberView.

GET `/v1/integrations/whatsapp/numbers/{phone_number_id}/answer-policy`#

Read the number's answer policy. Who answers when: the policy, its version, the limits, the presets built for this number (business hours pre-filled from your project's) and the stored policy's week in the number's time zone.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	`path`	string	Yes	Meta's phone number id of one of your connected numbers.

Responses

Code	Description
`200`	Success.
`401`	Missing or invalid API key.
`404`	Your project has no connected number with this id (`whatsapp_number_not_found`); an id of the wrong shape answers the same.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/integrations/whatsapp/numbers/{phone_number_id}/answer-policy" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppPolicyView.

PUT `/v1/integrations/whatsapp/numbers/{phone_number_id}/answer-policy`#

Replace the number's answer policy. Replaces the whole policy. version is the version your edit was based on: a stale one is refused and nothing changes. The read-only keys of the read are accepted and ignored, so the answer of the read is a valid body. A change applies from the next customer message; a conversation already waiting keeps the version it started under.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	`path`	string	Yes	Meta's phone number id of one of your connected numbers.

Request body

application/json Schema: WhatsAppPolicyPut

Field	Type	Required	Description
`policy`	`WhatsAppAnswerPolicy`	Yes	Who answers a number's WhatsApp messages, and when.
`version`	integer	Yes	The version this edit was based on.

Responses

Code	Description
`200`	Success.
`400`	The policy is not valid (`whatsapp_policy_invalid`, with `details[]` naming each field and its bound), or `version` is missing (`whatsapp_policy_version_required`).
`401`	Missing or invalid API key.
`402`	Your plan does not include WhatsApp (`feature_not_entitled`, with `missing_features: ["whatsapp_channel"]`), or the project has no plan (`no_subscription`). Nothing was changed.
`404`	Your project has no connected number with this id (`whatsapp_number_not_found`); an id of the wrong shape answers the same.
`409`	Someone changed the policy since your version (`whatsapp_policy_conflict`, with `current_version`).
`413`	The body is larger than 64 KiB (`body_too_large`).
`422`	The body is JSON this route cannot read (`invalid_request`): a field the document does not have, at any depth, a value of the wrong type, or more than one JSON value.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl -X PUT "https://api.voiceland.ai/v1/integrations/whatsapp/numbers/{phone_number_id}/answer-policy" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppPolicyView.

POST `/v1/integrations/whatsapp/numbers/{phone_number_id}/answer-policy/preview`#

Preview a policy's week. The week a policy would make in the number's time zone, with the windows now and the next changes. Writes nothing; never gated.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	`path`	string	Yes	Meta's phone number id of one of your connected numbers.

Request body

application/json Schema: WhatsAppPolicyPreviewRequest

Field	Type	Required	Description
`policy`	`WhatsAppAnswerPolicy`	Yes	Who answers a number's WhatsApp messages, and when.

Responses

Code	Description
`200`	Success.
`400`	The policy is not valid (`whatsapp_policy_invalid`, with `details[]`).
`401`	Missing or invalid API key.
`404`	Your project has no connected number with this id (`whatsapp_number_not_found`); an id of the wrong shape answers the same.
`413`	The body is larger than 64 KiB (`body_too_large`).
`422`	The body is JSON this route cannot read (`invalid_request`): a field the document does not have, at any depth, a value of the wrong type, or more than one JSON value.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl -X POST "https://api.voiceland.ai/v1/integrations/whatsapp/numbers/{phone_number_id}/answer-policy/preview" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppWeekPreview.

POST `/v1/integrations/whatsapp/numbers/{phone_number_id}/health`#

Re-check a number now. Reads the number's health, its details and its token from Meta again, and moves it back to live when Meta cleared what blocked it. Once per 30 seconds per number. No body.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	`path`	string	Yes	Meta's phone number id of one of your connected numbers.

Responses

Code	Description
`200`	Success.
`401`	Missing or invalid API key.
`402`	Your plan does not include WhatsApp (`feature_not_entitled`, with `missing_features: ["whatsapp_channel"]`), or the project has no plan (`no_subscription`). Nothing was changed.
`404`	Your project has no connected number with this id (`whatsapp_number_not_found`); an id of the wrong shape answers the same.
`409`	The number's token no longer works (`whatsapp_token_invalid`): reconnect the number in the console.
`413`	The body is larger than 1 KiB (`body_too_large`).
`429`	This number was re-checked less than 30 seconds ago (`whatsapp_rate_limited`). Meta's own throttling answers the same code with `meta_code` set.
`4XX`	Request error (validation, not-found, etc.).
`502`	Meta refused the request (`whatsapp_meta_error`, with `meta_code`); Meta's own text is not passed on.
`503`	The tenant secret vault could not be read right now (`whatsapp_vault_unavailable`); try again later.
`504`	Meta did not answer in time (`whatsapp_meta_timeout`); retry.
`5XX`	Server or upstream error.

Example request

curl -X POST "https://api.voiceland.ai/v1/integrations/whatsapp/numbers/{phone_number_id}/health" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppNumberView.

POST `/v1/integrations/whatsapp/numbers/{phone_number_id}/switch`#

Start or cancel moving a number off the WhatsApp Business app. For a number kept in the WhatsApp Business app: start marks the move to the Cloud API as begun (state: switching), which finishes when the number is connected again in the console; cancel undoes it.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	`path`	string	Yes	Meta's phone number id of one of your connected numbers.

Request body

application/json Schema: WhatsAppSwitchRequest

Field	Type	Required	Description
`action`	string	Yes	`start` or `cancel`.

Responses

Code	Description
`200`	Success.
`400`	`action` is not `start` or `cancel` (`invalid_request`).
`401`	Missing or invalid API key.
`402`	Your plan does not include WhatsApp (`feature_not_entitled`, with `missing_features: ["whatsapp_channel"]`), or the project has no plan (`no_subscription`). Nothing was changed.
`404`	Your project has no connected number with this id (`whatsapp_number_not_found`); an id of the wrong shape answers the same.
`409`	The number is not kept in the WhatsApp Business app, or is not live, limited or disconnected (`whatsapp_switch_not_allowed`).
`413`	The body is larger than 1 KiB (`body_too_large`).
`422`	The body is JSON this route cannot read (`invalid_request`): a field the document does not have, at any depth, a value of the wrong type, or more than one JSON value.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl -X POST "https://api.voiceland.ai/v1/integrations/whatsapp/numbers/{phone_number_id}/switch" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "start"
}'

A successful response returns a WhatsAppNumberView.

GET `/v1/integrations/whatsapp/numbers/{phone_number_id}/templates`#

List the number's message templates. The templates of the number's WhatsApp account as last synced (templates belong to the account and are shared by its numbers), by name then language. Templates are made and approved in WhatsApp Manager.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	`path`	string	Yes	Meta's phone number id of one of your connected numbers.
`status`	`query`	string		Only templates in this status, such as `APPROVED`, `PENDING` or `REJECTED`.

Responses

Code	Description
`200`	Success.
`400`	`status` is not an upper-case status (`invalid_request`).
`401`	Missing or invalid API key.
`404`	Your project has no connected number with this id (`whatsapp_number_not_found`); an id of the wrong shape answers the same.
`4XX`	Request error (validation, not-found, etc.).
`5XX`	Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/integrations/whatsapp/numbers/{phone_number_id}/templates" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppTemplateList.

POST `/v1/integrations/whatsapp/numbers/{phone_number_id}/templates/refresh`#

Sync the number's templates from Meta now. Reads every template from Meta and answers the synced list. 6 times an hour per WhatsApp account. No body.

Parameters

Name	In	Type	Required	Description
`phone_number_id`	`path`	string	Yes	Meta's phone number id of one of your connected numbers.

Responses

Code	Description
`200`	Success.
`401`	Missing or invalid API key.
`402`	Your plan does not include WhatsApp (`feature_not_entitled`, with `missing_features: ["whatsapp_channel"]`), or the project has no plan (`no_subscription`). Nothing was changed.
`403`	Meta has not granted this app access to the account yet (`whatsapp_meta_permission_denied`, with `meta_code`).
`404`	Your project has no connected number with this id (`whatsapp_number_not_found`); an id of the wrong shape answers the same.
`409`	The WhatsApp account's token no longer works (`whatsapp_token_invalid`): reconnect the number in the console.
`413`	The body is larger than 1 KiB (`body_too_large`).
`429`	The templates of this WhatsApp account were synced too often (`whatsapp_rate_limited`). Meta's own throttling answers the same code with `meta_code` set.
`4XX`	Request error (validation, not-found, etc.).
`502`	Meta refused the request (`whatsapp_meta_error`, with `meta_code`); Meta's own text is not passed on.
`503`	The tenant secret vault could not be read right now (`whatsapp_vault_unavailable`); try again later.
`504`	Meta did not answer in time (`whatsapp_meta_timeout`); retry.
`5XX`	Server or upstream error.

Example request

curl -X POST "https://api.voiceland.ai/v1/integrations/whatsapp/numbers/{phone_number_id}/templates/refresh" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a WhatsAppTemplateList.

Schemas#

Error#

Error envelope returned for non-2xx responses.

Field	Type	Required	Description
`error`	object	Yes

WhatsAppAnswerPolicy#

Who answers a number's WhatsApp messages, and when.

Field	Type	Required	Description
`closed_days`	array of string	Yes	Dates (`YYYY-MM-DD`, the number's time zone) the default window covers.
`preset`	string	Yes	The preset that last filled the form: `agent_all`, `team_first_5m`, `agent_outside_hours`, `people_only` or `custom`. Informational.
`reentry_line`	`WhatsAppPolicyLine`	Yes	A line sent before the agent's first reply after a pause.
`windows`	array of `WhatsAppPolicyWindow`	Yes	The windows in precedence order: business hours, custom windows, and last the one default window.

WhatsAppBoardRef#

Field	Type	Required	Description
`name`	string	Yes
`trigger`	string	Yes	`trigger.whatsapp_message` or `trigger.whatsapp_team_reply`.

WhatsAppBound#

Field	Type	Required
`max`	integer	Yes
`min`	integer	Yes
`step`	integer	Yes

WhatsAppBoundsView#

Field	Type	Required	Description
`agent_delay_s`	`WhatsAppBound`	Yes	A window's agent delay, in seconds.
`closed_days_max`	integer	Yes	Closed days per policy.
`custom_windows_max`	integer	Yes	Custom windows per policy.
`idle_close_min`	`WhatsAppBound`	Yes	Minutes of silence after which a session ends.
`line_chars_max`	integer	Yes	Characters of one line (the disclosure line, the re-entry line).
`line_languages_max`	integer	Yes	Languages of one line.
`lookback_days`	`WhatsAppBound`	Yes	How far back the agent reads; the maximum is this deployment's conversation retention.
`notify_emails_max`	integer	Yes	Addresses a number notifies.
`pause_minutes`	`WhatsAppBound`	Yes	A pause of `minutes`.
`quiet_minutes`	`WhatsAppBound`	Yes	A pause that ends once the conversation is quiet this long.
`quiet_reentry_hours`	`WhatsAppBound`	Yes	The quiet re-entry: hours without messages.
`ranges_per_day_max`	integer	Yes	Time ranges per day of a window.
`recent_messages`	`WhatsAppBound`	Yes	How many recent messages the agent reads at the start of a session.
`reply_chars_max`	integer	Yes	The longest staff reply, in characters.
`team_silence_minutes`	`WhatsAppBound`	Yes	The team-silence re-entry: minutes after a person's last message.
`team_wait_s`	`WhatsAppBound`	Yes	A window's wait for the team before the agent answers, in seconds; null in a policy is never.
`window_name_max`	integer	Yes	Characters of a window's name.

WhatsAppClaim#

Field	Type	Required	Description
`at`	string (date-time)	Yes
`by`	string	Yes

WhatsAppClosedDay#

Field	Type	Required	Description
`date`	string	Yes
`window_id`	string	Yes

WhatsAppCoexView#

Field	Type	Required	Description
`disconnect_by`	string
`disconnect_reason`	string
`disconnected_at`	string (date-time)
`last_app_activity_at`	string (date-time)
`reminder_sent_at`	string (date-time)
`switch_started_at`	string (date-time)

WhatsAppConfigView#

WhatsApp on this deployment. With WhatsApp off the answer is {"enabled": false} and nothing else.

Field	Type	Required	Description
`allowed_origins`	array of string		The caller's console origin when Meta's connection window may run on it (see `origin`), else empty; with no origin named, the deployment's own console. Never the whole list.
`app_id`	string		The Meta app the console's connection window runs with.
`bounds`	`WhatsAppBoundsView`		Every limit the settings and the answer policy are checked against.
`coexistence`	boolean		true when a number may stay in the WhatsApp Business app while the agent answers beside it.
`config_id`	string		The connection window's configuration at Meta.
`connect_extras`	map of object		Per connection mode, the extras the console passes to Meta's connection window.
`default_lines`	`WhatsAppDefaultLines`		The default lines for a language a number has not stored.
`early_access`	boolean		Always `false`: WhatsApp is generally available. Kept for clients that read it.
`enabled`	boolean	Yes	true when WhatsApp is enabled on this deployment.
`entitled`	boolean		true when your plan includes WhatsApp (`whatsapp_channel`).
`graph_version`	string		The Meta Graph API version this deployment calls.
`link_ttl_s`	integer		How long a pause or resume link in a notice works, in seconds.
`manager_url`	string		WhatsApp Manager, where templates and payment are managed.
`sdk_url`	string		Meta's JavaScript SDK the console loads for the connection window.

WhatsAppContactConversation#

Field	Type	Required	Description
`conversation_id`	string	Yes
`has_imported_history`	boolean	Yes	true when the conversation came with history from the WhatsApp Business app.
`last_inbound_at`	string (date-time)
`last_message_at`	string (date-time)
`number`	string	Yes	The business number, E.164.
`number_id`	string	Yes
`number_name`	string		The business number's verified name.
`phone`	string
`profile_name`	string
`user_id`	string
`window_open_until`	string (date-time)

WhatsAppContactConversationList#

Field	Type	Required	Description
`items`	array of `WhatsAppContactConversation`	Yes

WhatsAppConversationPage#

Field	Type	Required	Description
`items`	array of `WhatsAppConversationView`	Yes
`next_cursor`	string	Yes

WhatsAppConversationView#

Field	Type	Required	Description
`contact_id`	string	Yes	The linked contact; empty when none.
`customer`	`WhatsAppCustomerView`	Yes	The customer as WhatsApp names them.
`id`	string	Yes
`imported`	boolean	Yes
`last_inbound_at`	string (date-time)
`last_message_at`	string (date-time)
`last_message_preview`	string	Yes	The first 120 characters of the newest message, as stored.
`number`	string	Yes	The number's `phone_number_id`.
`origin`	string	Yes	Empty, `import` (from the WhatsApp Business app's history) or `team` (started from the app).
`session_open`	boolean	Yes	true while the agent has a session open here.
`status`	`WhatsAppStatus`	Yes	Who answers now, and until when.
`summary`	string		The single read only: the agent's summary of earlier sessions.
`summary_at`	string (date-time)
`unanswered_since`	string (date-time)		The oldest customer message nobody answered yet.
`window_open_until`	string (date-time)		When the 24-hour window the customer's last message opened closes.

WhatsAppCustomerView#

Field	Type	Description
`phone`	string	E.164, absent for a customer known by user id only.
`profile_name`	string
`user_id`	string	WhatsApp's user id of the customer.
`username`	string

WhatsAppDefaultLines#

Field	Type	Required	Description
`disclosure`	map of string	Yes	The default AI disclosure line per language; `{business}` stands for the number's verified name.

WhatsAppDisconnectView#

Field	Type	Required	Description
`phone_number_id`	string	Yes
`token_deleted`	boolean	Yes	true when the account's token was deleted with it.
`unsubscribed`	boolean	Yes	true when this was the WhatsApp account's last number here and Meta confirmed the release.

WhatsAppDuration#

Field	Type	Required	Description
`kind`	string	Yes	`minutes`, `end_of_day`, `window_end`, `quiet_minutes`, `manual` (until someone acts) or, on the hand-over trigger only, `until_team_reply`.
`minutes`	integer		With `minutes` (1 to 10080) and `quiet_minutes` (5 to 10080) only.

WhatsAppEmptyRequest#

Field	Type	Required	Description

WhatsAppHealthError#

Field	Type	Required
`entity_type`	string	Yes
`error_code`	integer	Yes
`error_description`	string	Yes
`possible_solution`	string	Yes

WhatsAppHealthView#

Field	Type	Required	Description
`additional_info`	array of string	Yes
`can_send_message`	string	Yes	`AVAILABLE`, `LIMITED`, `BLOCKED`, or empty before the first read.
`checked_at`	string (date-time)		When the health was read.
`errors`	array of `WhatsAppHealthError`	Yes	Meta's reasons when the number cannot send freely.
`payment_blocked_at`	string (date-time)		When Meta refused a send for a missing payment method.

WhatsAppImportView#

Field	Type	Required
`contacts_choice`	string	Yes
`contacts_imported`	integer	Yes
`contacts_matched`	integer	Yes
`contacts_state`	string	Yes
`deadline_at`	string (date-time)
`failure_code`	string
`finished_at`	string (date-time)
`history_choice`	string	Yes
`history_state`	string	Yes
`messages_imported`	integer	Yes
`messages_skipped`	integer	Yes
`onboarded_at`	string (date-time)
`phase`	integer	Yes
`progress`	integer	Yes
`state`	string	Yes

WhatsAppLinePatch#

Field	Type	Required	Description
`enabled`	boolean	Yes	Only your provider (Voiceland) switches the AI disclosure line off.
`texts`	map of string		The line per BCP-47 language (at most 12), 1 to 300 characters each.

WhatsAppLinesView#

Field	Type	Required	Description
`enabled`	boolean	Yes	true when the line is sent.
`texts`	map of string	Yes	The line per BCP-47 language, at most 300 characters each.

WhatsAppLocation#

Field	Type	Required
`address`	string
`latitude`	number	Yes
`longitude`	number	Yes
`name`	string

WhatsAppMediaView#

Field	Type	Required	Description
`download_path`	string		The media route, relative to the API base; present while the file is stored.
`filename`	string	Yes
`id`	string	Yes
`kind`	string	Yes
`mime_type`	string	Yes	The type the sender gave; the download is served as a safe type.
`size`	integer	Yes
`state`	string	Yes	`not_stored`, `stored`, `too_large`, `failed`, `purged` (removed by retention) or `archived`.
`transcript`	string	Yes	A voice note's transcript, when there is one.

WhatsAppMemoryPatch#

Field	Type	Required	Description
`idle_close_min`	integer	Yes
`lookback_days`	integer	Yes
`recent_messages`	integer	Yes
`summary_enabled`	boolean		Leave it out to keep the stored value.

WhatsAppMemoryView#

Field	Type	Required	Description
`idle_close_min`	integer	Yes	Minutes of silence after which a session ends (1 to 60).
`lookback_days`	integer	Yes	How far back the agent reads (1 to `retention_days`).
`recent_messages`	integer	Yes	Recent messages the agent reads at the start of a session (0 to 60).
`summary_enabled`	boolean	Yes	true when the agent keeps a summary of earlier sessions; reported false under pseudonymisation.

WhatsAppMessagePage#

Field	Type	Required	Description
`items`	array of `WhatsAppMessageView`	Yes
`next_cursor`	string	Yes

WhatsAppMessageView#

Field	Type	Required	Description
`at`	string (date-time)	Yes
`caption`	string	Yes
`contacts`	array of `WhatsAppSharedContact`	Yes
`direction`	string	Yes	`inbound` or `outbound`.
`error_code`	integer	Yes	Meta's error code of a failed message.
`id`	string	Yes	The message's id: Meta's wamid.
`location`	`WhatsAppLocation`
`media`	`WhatsAppMediaView`
`reaction`	`WhatsAppReaction`
`rep`	string	Yes	The person who wrote a console reply.
`rep_name`	string	Yes
`sender`	string	Yes	`customer`, `agent`, `team` or `automation` (an operations board).
`session_id`	string	Yes
`source`	string	Yes	A team or imported message: `app`, `console`, `api` or `import`.
`status`	string	Yes	`received`, `rate_limited`, `expired`, `accepted`, `sent`, `delivered`, `read`, `played` or `failed`.
`template`	`WhatsAppTemplateRef`
`text`	string	Yes
`type`	string	Yes
`wamid`	string	Yes

WhatsAppNumberList#

Field	Type	Required	Description
`items`	array of `WhatsAppNumberView`	Yes

WhatsAppNumberPatch#

Field	Type	Required	Description
`agent`	string
`create_contact_on_first_message`	boolean
`disclosure_line`	`WhatsAppLinePatch`
`memory`	`WhatsAppMemoryPatch`
`notify_emails`	array of string
`timezone`	string
`version`	integer

WhatsAppNumberView#

A connected WhatsApp number. Never a token, PIN or anything that configures one.

Field	Type	Required	Description
`agent`	string	Yes	The agent that answers; empty: your people only.
`agent_languages`	array of string	Yes	The agent's languages, the keys of the per-language lines.
`agent_missing`	boolean	Yes	true when the agent was deleted: nobody answers until another is chosen.
`boards`	array of `WhatsAppBoardRef`		The single read only: operations boards whose WhatsApp trigger listens to this number.
`business_id`	string	Yes
`coex`	`WhatsAppCoexView`		A number kept in the WhatsApp Business app: its activity and the move off it.
`connected_at`	string (date-time)
`create_contact_on_first_message`	boolean	Yes	true when a customer's first message creates a contact if none matches.
`demo`	boolean	Yes	true for a Voiceland demo number.
`disclosure_line`	`WhatsAppLinesView`	Yes	The AI disclosure line sent before the agent's first reply and again after a person replied.
`display_phone_number`	string	Yes	The number as Meta displays it.
`entitled`	boolean	Yes	false when your plan no longer includes WhatsApp: the data stays and nothing is answered.
`health`	`WhatsAppHealthView`	Yes	Meta's health of the number as last read.
`import`	`WhatsAppImportView`		A number kept in the WhatsApp Business app: the history and contacts import.
`last_webhook_at`	string (date-time)		When Meta last delivered something for the number (updated at most every five minutes).
`memory`	`WhatsAppMemoryView`	Yes	What the agent remembers between sessions.
`messaging_limit`	string	Yes	Meta's messaging limit tier, such as `TIER_250`.
`meta_status`	string	Yes
`mode`	string	Yes	`cloud_api`, or `coexistence` for a number kept in the WhatsApp Business app.
`name_status`	string	Yes
`notify_emails`	array of string	Yes	Who is told when the number needs attention; empty: the account's owner contact, or up to three of its administrators when there is none.
`ownership_type`	string	Yes
`phone_number_id`	string	Yes	Meta's id of the number: the routes' `phone_number_id`.
`policy_summary`	`WhatsAppPolicySummary`	Yes	The answer policy in one line.
`pseudonymized`	boolean	Yes	true under the `pseudonymize_at_rest` transcript policy: messages are stored pseudonymised and summaries are off.
`quality_rating`	string	Yes
`retention_days`	integer	Yes	The longest memory lookback: this deployment's conversation retention.
`state`	string	Yes	`live`, `limited`, `checking` (health not read yet), `blocked`, `payment_required` (Meta refuses sends until a payment method is added), `reconnect_required` (the token expired or was revoked: connect again in the console), `connected_elsewhere`, `switching`, `disconnected`, `connecting` or `disconnecting`.
`state_reason`	string	Yes	Why the number needs a person: Meta's disconnection reason (such as `PRIMARY_INACTIVITY`), `token_expired`, `token_revoked`, `token_invalid`, `payment` or `unknown`; empty otherwise.
`timezone`	string	Yes	The answer policy's clock (IANA).
`token`	`WhatsAppTokenView`	Yes	The business token's life; never the token.
`verified_name`	string	Yes	The business name Meta approved for the number.
`version`	integer	Yes	The number's version; send it back on a PATCH to refuse a change someone else made first.
`waba_id`	string	Yes	The WhatsApp Business Account the number belongs to; its templates are the account's.

WhatsAppOverride#

Field	Type	Required	Description
`at`	string (date-time)	Yes
`by`	string	Yes
`kind`	string	Yes
`mode`	string	Yes
`until`	string (date-time)
`via`	string	Yes	`console`, `api` or `link`.

WhatsAppPauseRequest#

Field	Type	Required	Description
`duration`	`WhatsAppDuration`	Yes	How long: `minutes`, `end_of_day`, `window_end`, `quiet_minutes` or `manual`.

WhatsAppPauseTrigger#

Field	Type	Required	Description
`duration`	`WhatsAppDuration`	Yes
`enabled`	boolean	Yes

WhatsAppPauseTriggers#

Field	Type	Required
`console`	`WhatsAppPauseTrigger`	Yes
`handover`	`WhatsAppPauseTrigger`	Yes
`takeover`	`WhatsAppToggle`	Yes
`team_app`	`WhatsAppPauseTrigger`	Yes

WhatsAppPolicyLine#

Field	Type	Required	Description
`enabled`	boolean	Yes
`texts`	map of string	Yes	The line per BCP-47 language, at most 300 characters each.

WhatsAppPolicyPreviewRequest#

Field	Type	Required	Description
`policy`	`WhatsAppAnswerPolicy`	Yes	Who answers a number's WhatsApp messages, and when.

WhatsAppPolicyPut#

Field	Type	Required	Description
`policy`	`WhatsAppAnswerPolicy`	Yes	Who answers a number's WhatsApp messages, and when.
`version`	integer	Yes	The version this edit was based on.

WhatsAppPolicySummary#

Field	Type	Required	Description
`preset`	string	Yes	The preset that last filled the policy, or `custom`.
`version`	integer	Yes	The policy's version.
`windows`	integer	Yes	How many windows the policy has.

WhatsAppPolicyView#

Field	Type	Required	Description
`bounds`	`WhatsAppBoundsView`	Yes
`default_preset`	string	Yes	The preset a new number of this mode starts with.
`phone_number_id`	string	Yes
`policy`	`WhatsAppAnswerPolicy`		Who answers a number's WhatsApp messages, and when.
`presets`	map of `WhatsAppAnswerPolicy`	Yes	The presets built for this number: `agent_all`, `team_first_5m`, `agent_outside_hours` and `people_only`.
`timezone`	string	Yes	The number's time zone: the policy's clock.
`updated_at`	string (date-time)
`updated_by`	string		Who saved the policy last.
`version`	integer	Yes	The policy's version; send it with the PUT.
`week`	`WhatsAppWeekPreview`		The stored policy's week in the number's time zone.

WhatsAppPolicyWindow#

Field	Type	Required	Description
`agent_delay_s`	integer	Yes	When the agent answers first: seconds it waits (0 to 600, step 10).
`agent_enabled`	boolean	Yes	false: people only in this window.
`answer_scope`	string	Yes	`all_unanswered` or `latest`.
`first_responder`	string	Yes	`agent` or `team`.
`id`	string	Yes	`business_hours`, `default`, or `c` and 1 to 15 letters or digits for a custom window.
`kind`	string	Yes	`business_hours`, `custom` or `default`.
`name`	string	Yes
`pause_triggers`	`WhatsAppPauseTriggers`	Yes
`reentry`	`WhatsAppReentryRules`	Yes
`schedule`	`WhatsAppSchedule`		When the window applies; the default window has none.
`team_wait_s`	integer		When the team answers first: seconds before the agent answers (60 to 86400, step 60); null: never.

WhatsAppReaction#

Field	Type	Required	Description
`emoji`	string
`message_id`	string	Yes

WhatsAppReentry#

Field	Type	Required	Description
`answer_pending`	boolean	Yes
`at`	string (date-time)
`minutes`	integer
`rule`	string	Yes	What brings the agent back first: `pause_end`, `team_silence`, `window_change`, `quiet` or `manual`.

WhatsAppReentryHours#

Field	Type	Required	Description
`enabled`	boolean	Yes
`hours`	integer	Yes

WhatsAppReentryMinutes#

Field	Type	Required	Description
`enabled`	boolean	Yes
`minutes`	integer	Yes

WhatsAppReentryPauseEnd#

Field	Type	Required	Description
`answer_pending`	boolean	Yes
`enabled`	boolean	Yes

WhatsAppReentryRules#

Field	Type	Required
`never`	boolean	Yes
`pause_end`	`WhatsAppReentryPauseEnd`	Yes
`quiet`	`WhatsAppReentryHours`	Yes
`team_silence`	`WhatsAppReentryMinutes`	Yes
`window_change`	`WhatsAppToggle`	Yes

WhatsAppReplyRequest#

Field	Type	Required	Description
`rep_name`	string		The name the conversation shows for the reply, at most 80 characters.
`text`	string	Yes	1 to 4,096 characters.

WhatsAppReplyView#

Field	Type	Required	Description
`conversation`	`WhatsAppConversationView`	Yes
`message`	`WhatsAppMessageView`	Yes

WhatsAppResumeRequest#

Field	Type	Required	Description
`hold`	`WhatsAppDuration`		Keep the agent answering until then: `minutes`, `end_of_day`, `window_end` or `manual`.

WhatsAppSchedule#

Field	Type	Required	Description
`days`	array of `WhatsAppScheduleDay`	Yes

WhatsAppScheduleDay#

Field	Type	Required	Description
`day`	string	Yes
`ranges`	array of `WhatsAppScheduleRange`

WhatsAppScheduleRange#

Field	Type	Required	Description
`end`	string	Yes
`start`	string	Yes

WhatsAppSharedContact#

Field	Type	Required
`emails`	array of string
`name`	string	Yes
`org`	string
`phones`	array of string

WhatsAppStatus#

Field	Type	Required
`chip`	`WhatsAppStatusChip`	Yes
`claim`	`WhatsAppClaim`
`hand_seq`	integer	Yes
`override`	`WhatsAppOverride`
`policy_version`	integer	Yes
`quiet_minutes`	integer
`reason`	string	Yes
`reentry`	`WhatsAppReentry`
`state`	string	Yes
`unanswered`	integer	Yes
`until`	string (date-time)
`until_kind`	string
`waiting_for`	string
`window`	string	Yes
`window_id`	string	Yes
`window_mode`	string	Yes
`window_open_until`	string (date-time)

WhatsAppStatusChip#

Field	Type	Required
`key`	string	Yes
`params`	map of string	Yes
`tone`	string	Yes

WhatsAppSwitchRequest#

Field	Type	Required	Description
`action`	string	Yes	`start` or `cancel`.

WhatsAppTemplateList#

Field	Type	Required	Description
`items`	array of `WhatsAppTemplateView`	Yes
`synced_at`	string (date-time)		When the templates were last synced from Meta.
`truncated`	boolean	Yes	true when the account has more than 2,000 templates: filter by status.

WhatsAppTemplateRef#

Field	Type	Required	Description
`language`	string	Yes
`name`	string	Yes

WhatsAppTemplateView#

Field	Type	Required	Description
`body_params`	integer	Yes
`body_text`	string	Yes
`category`	string	Yes
`header_format`	string	Yes	`NONE`, `TEXT`, `IMAGE`, `VIDEO`, `DOCUMENT` or `LOCATION`.
`id`	string	Yes
`language`	string	Yes
`last_synced_at`	string (date-time)
`name`	string	Yes
`named_params`	array of string	Yes
`parameter_format`	string	Yes	`POSITIONAL` or `NAMED`.
`quality`	string	Yes
`rejected_reason`	string	Yes
`status`	string	Yes	Meta's status, such as `APPROVED`, `PENDING`, `REJECTED` or `PAUSED`.
`unsupported`	string	Yes	Why an operations board cannot send this template; empty when it can.
`variables`	array of string	Yes	The values a send fills, in order.
`waba_id`	string	Yes

WhatsAppToggle#

Field	Type	Required	Description
`enabled`	boolean	Yes

WhatsAppTokenView#

Field	Type	Required	Description
`expires_at`	string (date-time)		When the business token expires; absent when it does not.
`expiring`	boolean	Yes	true within 7 days of the expiry: connect again in the console.
`invalid`	boolean	Yes	true when the token no longer works: connect again in the console.

WhatsAppWeekChange#

Field	Type	Required
`at`	string (date-time)	Yes
`mode`	string	Yes
`window_id`	string	Yes

WhatsAppWeekDay#

Field	Type	Required	Description
`day`	string	Yes
`segments`	array of `WhatsAppWeekSegment`	Yes

WhatsAppWeekNow#

Field	Type	Required
`local_time`	string	Yes
`mode`	string	Yes
`until`	string (date-time)
`window_id`	string	Yes

WhatsAppWeekPreview#

A policy's week in the number's time zone.

Field	Type	Required
`closed_days`	array of `WhatsAppClosedDay`	Yes
`days`	array of `WhatsAppWeekDay`	Yes
`next_changes`	array of `WhatsAppWeekChange`	Yes
`now`	`WhatsAppWeekNow`	Yes
`timezone`	string	Yes

WhatsAppWeekSegment#

Field	Type	Required	Description
`agent_delay_s`	integer	Yes
`end`	string	Yes
`mode`	string	Yes	`agent`, `team_then_agent`, `team_only` or `agent_off`.
`start`	string	Yes
`team_wait_s`	integer
`window_id`	string	Yes
`window_kind`	string	Yes
`window_name`	string	Yes

GET /v1/contacts/{id}/whatsapp#

Parameters

Responses

Example request

GET /v1/integrations/whatsapp/config#

Parameters

Responses

Example request

GET /v1/integrations/whatsapp/conversations#

Parameters

Responses

Example request

GET /v1/integrations/whatsapp/conversations/{conversation_id}#

Parameters

Responses

Example request

POST /v1/integrations/whatsapp/conversations/{conversation_id}/claim#

Parameters

Request body

Responses

Example request

GET /v1/integrations/whatsapp/conversations/{conversation_id}/media/{media_id}#

Parameters

Responses

Example request

GET /v1/integrations/whatsapp/conversations/{conversation_id}/messages#

Parameters

Responses

Example request

POST /v1/integrations/whatsapp/conversations/{conversation_id}/messages#

Parameters

Request body

Responses

Example request

POST /v1/integrations/whatsapp/conversations/{conversation_id}/pause#

Parameters

Request body

Responses

Example request

POST /v1/integrations/whatsapp/conversations/{conversation_id}/release#

Parameters

Request body

Responses

Example request

POST /v1/integrations/whatsapp/conversations/{conversation_id}/resume#

Parameters

Request body

Responses

Example request

DELETE /v1/integrations/whatsapp/conversations/{conversation_id}/summary#

Parameters

Responses

Example request

GET /v1/integrations/whatsapp/numbers#

Responses

Example request

DELETE /v1/integrations/whatsapp/numbers/{phone_number_id}#

Parameters

Responses

Example request

GET /v1/integrations/whatsapp/numbers/{phone_number_id}#

Parameters

Responses

Example request

PATCH /v1/integrations/whatsapp/numbers/{phone_number_id}#

Parameters

Request body

Responses

Example request

GET /v1/integrations/whatsapp/numbers/{phone_number_id}/answer-policy#

Parameters

Responses

Example request

PUT /v1/integrations/whatsapp/numbers/{phone_number_id}/answer-policy#

Parameters

Request body

Responses

Example request

POST /v1/integrations/whatsapp/numbers/{phone_number_id}/answer-policy/preview#

Parameters

GET `/v1/contacts/{id}/whatsapp`#

GET `/v1/integrations/whatsapp/config`#

GET `/v1/integrations/whatsapp/conversations`#

GET `/v1/integrations/whatsapp/conversations/{conversation_id}`#

POST `/v1/integrations/whatsapp/conversations/{conversation_id}/claim`#

GET `/v1/integrations/whatsapp/conversations/{conversation_id}/media/{media_id}`#

GET `/v1/integrations/whatsapp/conversations/{conversation_id}/messages`#

POST `/v1/integrations/whatsapp/conversations/{conversation_id}/messages`#

POST `/v1/integrations/whatsapp/conversations/{conversation_id}/pause`#

POST `/v1/integrations/whatsapp/conversations/{conversation_id}/release`#

POST `/v1/integrations/whatsapp/conversations/{conversation_id}/resume`#

DELETE `/v1/integrations/whatsapp/conversations/{conversation_id}/summary`#

GET `/v1/integrations/whatsapp/numbers`#

DELETE `/v1/integrations/whatsapp/numbers/{phone_number_id}`#

GET `/v1/integrations/whatsapp/numbers/{phone_number_id}`#

PATCH `/v1/integrations/whatsapp/numbers/{phone_number_id}`#

GET `/v1/integrations/whatsapp/numbers/{phone_number_id}/answer-policy`#

PUT `/v1/integrations/whatsapp/numbers/{phone_number_id}/answer-policy`#

POST `/v1/integrations/whatsapp/numbers/{phone_number_id}/answer-policy/preview`#

POST `/v1/integrations/whatsapp/numbers/{phone_number_id}/health`#

POST `/v1/integrations/whatsapp/numbers/{phone_number_id}/switch`#

GET `/v1/integrations/whatsapp/numbers/{phone_number_id}/templates`#

POST `/v1/integrations/whatsapp/numbers/{phone_number_id}/templates/refresh`#