WhatsApp: API-Referenz von Voiceland AI

Die Endpoints der Gruppe WhatsApp der Voiceland AI API, mit Parametern, Schemata und Beispielen mit curl.

Zuletzt aktualisiert: 2026-10-20

Die Beschreibungen der Endpoints und der Felder erscheinen auf Englisch, genau so, wie die API sie ausliefert. Das ist Absicht: Sie lesen hier, was Sie auch in den Antworten sehen.

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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`id`	`path`	string	Ja	Contact id.
`limit`	`query`	integer		At most this many, 1 to 200 (default 50); larger values are capped.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`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.

Antworten

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

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Beschreibung
`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.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein WhatsAppConversationPage.

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

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

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`conversation_id`	`path`	string	Ja	Conversation id: `wc` and 16 letters or digits.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`conversation_id`	`path`	string	Ja	Conversation id: `wc` and 16 letters or digits.

Anfragetext

application/json Schema: WhatsAppEmptyRequest

Feld	Typ	Erforderlich	Beschreibung

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`conversation_id`	`path`	string	Ja	Conversation id: `wc` and 16 letters or digits.
`media_id`	`path`	string	Ja	Media id: `wm` and 16 hex digits, a message's `media.id`.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`conversation_id`	`path`	string	Ja	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.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`conversation_id`	`path`	string	Ja	Conversation id: `wc` and 16 letters or digits.

Anfragetext

application/json Schema: WhatsAppReplyRequest

Feld	Typ	Erforderlich	Beschreibung
`rep_name`	string		The name the conversation shows for the reply, at most 80 characters.
`text`	string	Ja	1 to 4,096 characters.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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."
}'

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`conversation_id`	`path`	string	Ja	Conversation id: `wc` and 16 letters or digits.

Anfragetext

application/json Schema: WhatsAppPauseRequest

Feld	Typ	Erforderlich	Beschreibung
`duration`	`WhatsAppDuration`	Ja	How long: `minutes`, `end_of_day`, `window_end`, `quiet_minutes` or `manual`.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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
  }
}'

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`conversation_id`	`path`	string	Ja	Conversation id: `wc` and 16 letters or digits.

Anfragetext

application/json Schema: WhatsAppEmptyRequest

Feld	Typ	Erforderlich	Beschreibung

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`conversation_id`	`path`	string	Ja	Conversation id: `wc` and 16 letters or digits.

Anfragetext

application/json Schema: WhatsAppResumeRequest

Feld	Typ	Erforderlich	Beschreibung
`hold`	`WhatsAppDuration`		Keep the agent answering until then: `minutes`, `end_of_day`, `window_end` or `manual`.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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"
  }
}'

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`conversation_id`	`path`	string	Ja	Conversation id: `wc` and 16 letters or digits.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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.

Antworten

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

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`phone_number_id`	`path`	string	Ja	Meta's phone number id of one of your connected numbers.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein 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).

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`phone_number_id`	`path`	string	Ja	Meta's phone number id of one of your connected numbers.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein 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).

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`phone_number_id`	`path`	string	Ja	Meta's phone number id of one of your connected numbers.

Anfragetext

application/json Schema: WhatsAppNumberPatch

Feld	Typ	Erforderlich	Beschreibung
`agent`	string
`create_contact_on_first_message`	boolean
`disclosure_line`	`WhatsAppLinePatch`
`memory`	`WhatsAppMemoryPatch`
`notify_emails`	array of string
`timezone`	string
`version`	integer

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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
}'

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`phone_number_id`	`path`	string	Ja	Meta's phone number id of one of your connected numbers.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`phone_number_id`	`path`	string	Ja	Meta's phone number id of one of your connected numbers.

Anfragetext

application/json Schema: WhatsAppPolicyPut

Feld	Typ	Erforderlich	Beschreibung
`policy`	`WhatsAppAnswerPolicy`	Ja	Who answers a number's WhatsApp messages, and when.
`version`	integer	Ja	The version this edit was based on.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`phone_number_id`	`path`	string	Ja	Meta's phone number id of one of your connected numbers.

Anfragetext

application/json Schema: WhatsAppPolicyPreviewRequest

Feld	Typ	Erforderlich	Beschreibung
`policy`	`WhatsAppAnswerPolicy`	Ja	Who answers a number's WhatsApp messages, and when.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`phone_number_id`	`path`	string	Ja	Meta's phone number id of one of your connected numbers.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`phone_number_id`	`path`	string	Ja	Meta's phone number id of one of your connected numbers.

Anfragetext

application/json Schema: WhatsAppSwitchRequest

Feld	Typ	Erforderlich	Beschreibung
`action`	string	Ja	`start` or `cancel`.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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"
}'

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`phone_number_id`	`path`	string	Ja	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`.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein 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.

Parameter

Name	Ort	Typ	Erforderlich	Beschreibung
`phone_number_id`	`path`	string	Ja	Meta's phone number id of one of your connected numbers.

Antworten

Code	Beschreibung
`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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein WhatsAppTemplateList.

Schemata#

Error#

Error envelope returned for non-2xx responses.

Feld	Typ	Erforderlich	Beschreibung
`error`	object	Ja

WhatsAppAnswerPolicy#

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

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

WhatsAppBoardRef#

Feld	Typ	Erforderlich	Beschreibung
`name`	string	Ja
`trigger`	string	Ja	`trigger.whatsapp_message` or `trigger.whatsapp_team_reply`.

WhatsAppBound#

Feld	Typ	Erforderlich
`max`	integer	Ja
`min`	integer	Ja
`step`	integer	Ja

WhatsAppBoundsView#

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

WhatsAppClaim#

Feld	Typ	Erforderlich	Beschreibung
`at`	string (date-time)	Ja
`by`	string	Ja

WhatsAppClosedDay#

Feld	Typ	Erforderlich	Beschreibung
`date`	string	Ja
`window_id`	string	Ja

WhatsAppCoexView#

Feld	Typ	Erforderlich	Beschreibung
`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.

Feld	Typ	Erforderlich	Beschreibung
`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	Ja	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#

Feld	Typ	Erforderlich	Beschreibung
`conversation_id`	string	Ja
`has_imported_history`	boolean	Ja	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	Ja	The business number, E.164.
`number_id`	string	Ja
`number_name`	string		The business number's verified name.
`phone`	string
`profile_name`	string
`user_id`	string
`window_open_until`	string (date-time)

WhatsAppContactConversationList#

Feld	Typ	Erforderlich	Beschreibung
`items`	array of `WhatsAppContactConversation`	Ja

WhatsAppConversationPage#

Feld	Typ	Erforderlich	Beschreibung
`items`	array of `WhatsAppConversationView`	Ja
`next_cursor`	string	Ja

WhatsAppConversationView#

Feld	Typ	Erforderlich	Beschreibung
`contact_id`	string	Ja	The linked contact; empty when none.
`customer`	`WhatsAppCustomerView`	Ja	The customer as WhatsApp names them.
`id`	string	Ja
`imported`	boolean	Ja
`last_inbound_at`	string (date-time)
`last_message_at`	string (date-time)
`last_message_preview`	string	Ja	The first 120 characters of the newest message, as stored.
`number`	string	Ja	The number's `phone_number_id`.
`origin`	string	Ja	Empty, `import` (from the WhatsApp Business app's history) or `team` (started from the app).
`session_open`	boolean	Ja	true while the agent has a session open here.
`status`	`WhatsAppStatus`	Ja	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#

Feld	Typ	Beschreibung
`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#

Feld	Typ	Erforderlich	Beschreibung
`disclosure`	map of string	Ja	The default AI disclosure line per language; `{business}` stands for the number's verified name.

WhatsAppDisconnectView#

Feld	Typ	Erforderlich	Beschreibung
`phone_number_id`	string	Ja
`token_deleted`	boolean	Ja	true when the account's token was deleted with it.
`unsubscribed`	boolean	Ja	true when this was the WhatsApp account's last number here and Meta confirmed the release.

WhatsAppDuration#

Feld	Typ	Erforderlich	Beschreibung
`kind`	string	Ja	`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#

Feld	Typ	Erforderlich	Beschreibung

WhatsAppHealthError#

Feld	Typ	Erforderlich
`entity_type`	string	Ja
`error_code`	integer	Ja
`error_description`	string	Ja
`possible_solution`	string	Ja

WhatsAppHealthView#

Feld	Typ	Erforderlich	Beschreibung
`additional_info`	array of string	Ja
`can_send_message`	string	Ja	`AVAILABLE`, `LIMITED`, `BLOCKED`, or empty before the first read.
`checked_at`	string (date-time)		When the health was read.
`errors`	array of `WhatsAppHealthError`	Ja	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#

Feld	Typ	Erforderlich
`contacts_choice`	string	Ja
`contacts_imported`	integer	Ja
`contacts_matched`	integer	Ja
`contacts_state`	string	Ja
`deadline_at`	string (date-time)
`failure_code`	string
`finished_at`	string (date-time)
`history_choice`	string	Ja
`history_state`	string	Ja
`messages_imported`	integer	Ja
`messages_skipped`	integer	Ja
`onboarded_at`	string (date-time)
`phase`	integer	Ja
`progress`	integer	Ja
`state`	string	Ja

WhatsAppLinePatch#

Feld	Typ	Erforderlich	Beschreibung
`enabled`	boolean	Ja	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#

Feld	Typ	Erforderlich	Beschreibung
`enabled`	boolean	Ja	true when the line is sent.
`texts`	map of string	Ja	The line per BCP-47 language, at most 300 characters each.

WhatsAppLocation#

Feld	Typ	Erforderlich
`address`	string
`latitude`	number	Ja
`longitude`	number	Ja
`name`	string

WhatsAppMediaView#

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

WhatsAppMemoryPatch#

Feld	Typ	Erforderlich	Beschreibung
`idle_close_min`	integer	Ja
`lookback_days`	integer	Ja
`recent_messages`	integer	Ja
`summary_enabled`	boolean		Leave it out to keep the stored value.

WhatsAppMemoryView#

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

WhatsAppMessagePage#

Feld	Typ	Erforderlich	Beschreibung
`items`	array of `WhatsAppMessageView`	Ja
`next_cursor`	string	Ja

WhatsAppMessageView#

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

WhatsAppNumberList#

Feld	Typ	Erforderlich	Beschreibung
`items`	array of `WhatsAppNumberView`	Ja

WhatsAppNumberPatch#

Feld	Typ	Erforderlich	Beschreibung
`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.

Feld	Typ	Erforderlich	Beschreibung
`agent`	string	Ja	The agent that answers; empty: your people only.
`agent_languages`	array of string	Ja	The agent's languages, the keys of the per-language lines.
`agent_missing`	boolean	Ja	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	Ja
`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	Ja	true when a customer's first message creates a contact if none matches.
`demo`	boolean	Ja	true for a Voiceland demo number.
`disclosure_line`	`WhatsAppLinesView`	Ja	The AI disclosure line sent before the agent's first reply and again after a person replied.
`display_phone_number`	string	Ja	The number as Meta displays it.
`entitled`	boolean	Ja	false when your plan no longer includes WhatsApp: the data stays and nothing is answered.
`health`	`WhatsAppHealthView`	Ja	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`	Ja	What the agent remembers between sessions.
`messaging_limit`	string	Ja	Meta's messaging limit tier, such as `TIER_250`.
`meta_status`	string	Ja
`mode`	string	Ja	`cloud_api`, or `coexistence` for a number kept in the WhatsApp Business app.
`name_status`	string	Ja
`notify_emails`	array of string	Ja	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	Ja
`phone_number_id`	string	Ja	Meta's id of the number: the routes' `phone_number_id`.
`policy_summary`	`WhatsAppPolicySummary`	Ja	The answer policy in one line.
`pseudonymized`	boolean	Ja	true under the `pseudonymize_at_rest` transcript policy: messages are stored pseudonymised and summaries are off.
`quality_rating`	string	Ja
`retention_days`	integer	Ja	The longest memory lookback: this deployment's conversation retention.
`state`	string	Ja	`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	Ja	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	Ja	The answer policy's clock (IANA).
`token`	`WhatsAppTokenView`	Ja	The business token's life; never the token.
`verified_name`	string	Ja	The business name Meta approved for the number.
`version`	integer	Ja	The number's version; send it back on a PATCH to refuse a change someone else made first.
`waba_id`	string	Ja	The WhatsApp Business Account the number belongs to; its templates are the account's.

WhatsAppOverride#

Feld	Typ	Erforderlich	Beschreibung
`at`	string (date-time)	Ja
`by`	string	Ja
`kind`	string	Ja
`mode`	string	Ja
`until`	string (date-time)
`via`	string	Ja	`console`, `api` or `link`.

WhatsAppPauseRequest#

Feld	Typ	Erforderlich	Beschreibung
`duration`	`WhatsAppDuration`	Ja	How long: `minutes`, `end_of_day`, `window_end`, `quiet_minutes` or `manual`.

WhatsAppPauseTrigger#

Feld	Typ	Erforderlich	Beschreibung
`duration`	`WhatsAppDuration`	Ja
`enabled`	boolean	Ja

WhatsAppPauseTriggers#

Feld	Typ	Erforderlich
`console`	`WhatsAppPauseTrigger`	Ja
`handover`	`WhatsAppPauseTrigger`	Ja
`takeover`	`WhatsAppToggle`	Ja
`team_app`	`WhatsAppPauseTrigger`	Ja

WhatsAppPolicyLine#

Feld	Typ	Erforderlich	Beschreibung
`enabled`	boolean	Ja
`texts`	map of string	Ja	The line per BCP-47 language, at most 300 characters each.

WhatsAppPolicyPreviewRequest#

Feld	Typ	Erforderlich	Beschreibung
`policy`	`WhatsAppAnswerPolicy`	Ja	Who answers a number's WhatsApp messages, and when.

WhatsAppPolicyPut#

Feld	Typ	Erforderlich	Beschreibung
`policy`	`WhatsAppAnswerPolicy`	Ja	Who answers a number's WhatsApp messages, and when.
`version`	integer	Ja	The version this edit was based on.

WhatsAppPolicySummary#

Feld	Typ	Erforderlich	Beschreibung
`preset`	string	Ja	The preset that last filled the policy, or `custom`.
`version`	integer	Ja	The policy's version.
`windows`	integer	Ja	How many windows the policy has.

WhatsAppPolicyView#

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

WhatsAppPolicyWindow#

Feld	Typ	Erforderlich	Beschreibung
`agent_delay_s`	integer	Ja	When the agent answers first: seconds it waits (0 to 600, step 10).
`agent_enabled`	boolean	Ja	false: people only in this window.
`answer_scope`	string	Ja	`all_unanswered` or `latest`.
`first_responder`	string	Ja	`agent` or `team`.
`id`	string	Ja	`business_hours`, `default`, or `c` and 1 to 15 letters or digits for a custom window.
`kind`	string	Ja	`business_hours`, `custom` or `default`.
`name`	string	Ja
`pause_triggers`	`WhatsAppPauseTriggers`	Ja
`reentry`	`WhatsAppReentryRules`	Ja
`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#

Feld	Typ	Erforderlich	Beschreibung
`emoji`	string
`message_id`	string	Ja

WhatsAppReentry#

Feld	Typ	Erforderlich	Beschreibung
`answer_pending`	boolean	Ja
`at`	string (date-time)
`minutes`	integer
`rule`	string	Ja	What brings the agent back first: `pause_end`, `team_silence`, `window_change`, `quiet` or `manual`.

WhatsAppReentryHours#

Feld	Typ	Erforderlich	Beschreibung
`enabled`	boolean	Ja
`hours`	integer	Ja

WhatsAppReentryMinutes#

Feld	Typ	Erforderlich	Beschreibung
`enabled`	boolean	Ja
`minutes`	integer	Ja

WhatsAppReentryPauseEnd#

Feld	Typ	Erforderlich	Beschreibung
`answer_pending`	boolean	Ja
`enabled`	boolean	Ja

WhatsAppReentryRules#

Feld	Typ	Erforderlich
`never`	boolean	Ja
`pause_end`	`WhatsAppReentryPauseEnd`	Ja
`quiet`	`WhatsAppReentryHours`	Ja
`team_silence`	`WhatsAppReentryMinutes`	Ja
`window_change`	`WhatsAppToggle`	Ja

WhatsAppReplyRequest#

Feld	Typ	Erforderlich	Beschreibung
`rep_name`	string		The name the conversation shows for the reply, at most 80 characters.
`text`	string	Ja	1 to 4,096 characters.

WhatsAppReplyView#

Feld	Typ	Erforderlich	Beschreibung
`conversation`	`WhatsAppConversationView`	Ja
`message`	`WhatsAppMessageView`	Ja

WhatsAppResumeRequest#

Feld	Typ	Erforderlich	Beschreibung
`hold`	`WhatsAppDuration`		Keep the agent answering until then: `minutes`, `end_of_day`, `window_end` or `manual`.

WhatsAppSchedule#

Feld	Typ	Erforderlich	Beschreibung
`days`	array of `WhatsAppScheduleDay`	Ja

WhatsAppScheduleDay#

Feld	Typ	Erforderlich	Beschreibung
`day`	string	Ja
`ranges`	array of `WhatsAppScheduleRange`

WhatsAppScheduleRange#

Feld	Typ	Erforderlich	Beschreibung
`end`	string	Ja
`start`	string	Ja

WhatsAppSharedContact#

Feld	Typ	Erforderlich
`emails`	array of string
`name`	string	Ja
`org`	string
`phones`	array of string

WhatsAppStatus#

Feld	Typ	Erforderlich
`chip`	`WhatsAppStatusChip`	Ja
`claim`	`WhatsAppClaim`
`hand_seq`	integer	Ja
`override`	`WhatsAppOverride`
`policy_version`	integer	Ja
`quiet_minutes`	integer
`reason`	string	Ja
`reentry`	`WhatsAppReentry`
`state`	string	Ja
`unanswered`	integer	Ja
`until`	string (date-time)
`until_kind`	string
`waiting_for`	string
`window`	string	Ja
`window_id`	string	Ja
`window_mode`	string	Ja
`window_open_until`	string (date-time)

WhatsAppStatusChip#

Feld	Typ	Erforderlich
`key`	string	Ja
`params`	map of string	Ja
`tone`	string	Ja

WhatsAppSwitchRequest#

Feld	Typ	Erforderlich	Beschreibung
`action`	string	Ja	`start` or `cancel`.

WhatsAppTemplateList#

Feld	Typ	Erforderlich	Beschreibung
`items`	array of `WhatsAppTemplateView`	Ja
`synced_at`	string (date-time)		When the templates were last synced from Meta.
`truncated`	boolean	Ja	true when the account has more than 2,000 templates: filter by status.

WhatsAppTemplateRef#

Feld	Typ	Erforderlich	Beschreibung
`language`	string	Ja
`name`	string	Ja

WhatsAppTemplateView#

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

WhatsAppToggle#

Feld	Typ	Erforderlich	Beschreibung
`enabled`	boolean	Ja

WhatsAppTokenView#

Feld	Typ	Erforderlich	Beschreibung
`expires_at`	string (date-time)		When the business token expires; absent when it does not.
`expiring`	boolean	Ja	true within 7 days of the expiry: connect again in the console.
`invalid`	boolean	Ja	true when the token no longer works: connect again in the console.

WhatsAppWeekChange#

Feld	Typ	Erforderlich
`at`	string (date-time)	Ja
`mode`	string	Ja
`window_id`	string	Ja

WhatsAppWeekDay#

Feld	Typ	Erforderlich	Beschreibung
`day`	string	Ja
`segments`	array of `WhatsAppWeekSegment`	Ja

WhatsAppWeekNow#

Feld	Typ	Erforderlich
`local_time`	string	Ja
`mode`	string	Ja
`until`	string (date-time)
`window_id`	string	Ja

WhatsAppWeekPreview#

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

Feld	Typ	Erforderlich
`closed_days`	array of `WhatsAppClosedDay`	Ja
`days`	array of `WhatsAppWeekDay`	Ja
`next_changes`	array of `WhatsAppWeekChange`	Ja
`now`	`WhatsAppWeekNow`	Ja
`timezone`	string	Ja

WhatsAppWeekSegment#

Feld	Typ	Erforderlich	Beschreibung
`agent_delay_s`	integer	Ja
`end`	string	Ja
`mode`	string	Ja	`agent`, `team_then_agent`, `team_only` or `agent_off`.
`start`	string	Ja
`team_wait_s`	integer
`window_id`	string	Ja
`window_kind`	string	Ja
`window_name`	string	Ja

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

Parameter

Antworten

Beispielanfrage

GET /v1/integrations/whatsapp/config#

Parameter

Antworten

Beispielanfrage

GET /v1/integrations/whatsapp/conversations#

Parameter

Antworten

Beispielanfrage

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

Parameter

Antworten

Beispielanfrage

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

Parameter

Anfragetext

Antworten

Beispielanfrage

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

Parameter

Antworten

Beispielanfrage

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

Parameter

Antworten

Beispielanfrage

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

Parameter

Anfragetext

Antworten

Beispielanfrage

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

Parameter

Anfragetext

Antworten

Beispielanfrage

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

Parameter

Anfragetext

Antworten

Beispielanfrage

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

Parameter

Anfragetext

Antworten

Beispielanfrage

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

Parameter

Antworten

Beispielanfrage

GET /v1/integrations/whatsapp/numbers#

Antworten

Beispielanfrage

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

Parameter

Antworten

Beispielanfrage

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

Parameter

Antworten

Beispielanfrage

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

Parameter

Anfragetext

Antworten

Beispielanfrage

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

Parameter

Antworten

Beispielanfrage

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

Parameter

Anfragetext

Antworten

Beispielanfrage

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

Parameter

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`#