WhatsApp: riferimento API di Voiceland AI

Gli endpoint del gruppo WhatsApp dell'API Voiceland AI, con parametri, schemi ed esempi curl.

Ultimo aggiornamento: 2026-10-20

Le descrizioni degli endpoint e dei campi restano in inglese, esattamente come le pubblica l'API. È una scelta voluta: qui legge ciò che vedrà anche nelle risposte.

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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`id`	`path`	string	Sì	Contact id.
`limit`	`query`	integer		At most this many, 1 to 200 (default 50); larger values are capped.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`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.

Risposte

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

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Descrizione
`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.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un WhatsAppConversationPage.

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

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

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`conversation_id`	`path`	string	Sì	Conversation id: `wc` and 16 letters or digits.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`conversation_id`	`path`	string	Sì	Conversation id: `wc` and 16 letters or digits.

Corpo della richiesta

application/json Schema: WhatsAppEmptyRequest

Campo	Tipo	Obbligatorio	Descrizione

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`conversation_id`	`path`	string	Sì	Conversation id: `wc` and 16 letters or digits.
`media_id`	`path`	string	Sì	Media id: `wm` and 16 hex digits, a message's `media.id`.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`conversation_id`	`path`	string	Sì	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.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`conversation_id`	`path`	string	Sì	Conversation id: `wc` and 16 letters or digits.

Corpo della richiesta

application/json Schema: WhatsAppReplyRequest

Campo	Tipo	Obbligatorio	Descrizione
`rep_name`	string		The name the conversation shows for the reply, at most 80 characters.
`text`	string	Sì	1 to 4,096 characters.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`conversation_id`	`path`	string	Sì	Conversation id: `wc` and 16 letters or digits.

Corpo della richiesta

application/json Schema: WhatsAppPauseRequest

Campo	Tipo	Obbligatorio	Descrizione
`duration`	`WhatsAppDuration`	Sì	How long: `minutes`, `end_of_day`, `window_end`, `quiet_minutes` or `manual`.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`conversation_id`	`path`	string	Sì	Conversation id: `wc` and 16 letters or digits.

Corpo della richiesta

application/json Schema: WhatsAppEmptyRequest

Campo	Tipo	Obbligatorio	Descrizione

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`conversation_id`	`path`	string	Sì	Conversation id: `wc` and 16 letters or digits.

Corpo della richiesta

application/json Schema: WhatsAppResumeRequest

Campo	Tipo	Obbligatorio	Descrizione
`hold`	`WhatsAppDuration`		Keep the agent answering until then: `minutes`, `end_of_day`, `window_end` or `manual`.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`conversation_id`	`path`	string	Sì	Conversation id: `wc` and 16 letters or digits.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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.

Risposte

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

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`phone_number_id`	`path`	string	Sì	Meta's phone number id of one of your connected numbers.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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).

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`phone_number_id`	`path`	string	Sì	Meta's phone number id of one of your connected numbers.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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).

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`phone_number_id`	`path`	string	Sì	Meta's phone number id of one of your connected numbers.

Corpo della richiesta

application/json Schema: WhatsAppNumberPatch

Campo	Tipo	Obbligatorio	Descrizione
`agent`	string
`create_contact_on_first_message`	boolean
`disclosure_line`	`WhatsAppLinePatch`
`memory`	`WhatsAppMemoryPatch`
`notify_emails`	array of string
`timezone`	string
`version`	integer

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`phone_number_id`	`path`	string	Sì	Meta's phone number id of one of your connected numbers.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`phone_number_id`	`path`	string	Sì	Meta's phone number id of one of your connected numbers.

Corpo della richiesta

application/json Schema: WhatsAppPolicyPut

Campo	Tipo	Obbligatorio	Descrizione
`policy`	`WhatsAppAnswerPolicy`	Sì	Who answers a number's WhatsApp messages, and when.
`version`	integer	Sì	The version this edit was based on.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`phone_number_id`	`path`	string	Sì	Meta's phone number id of one of your connected numbers.

Corpo della richiesta

application/json Schema: WhatsAppPolicyPreviewRequest

Campo	Tipo	Obbligatorio	Descrizione
`policy`	`WhatsAppAnswerPolicy`	Sì	Who answers a number's WhatsApp messages, and when.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`phone_number_id`	`path`	string	Sì	Meta's phone number id of one of your connected numbers.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`phone_number_id`	`path`	string	Sì	Meta's phone number id of one of your connected numbers.

Corpo della richiesta

application/json Schema: WhatsAppSwitchRequest

Campo	Tipo	Obbligatorio	Descrizione
`action`	string	Sì	`start` or `cancel`.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`phone_number_id`	`path`	string	Sì	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`.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un 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.

Parametri

Nome	Posizione	Tipo	Obbligatorio	Descrizione
`phone_number_id`	`path`	string	Sì	Meta's phone number id of one of your connected numbers.

Risposte

Codice	Descrizione
`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.

Esempio di richiesta

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

Una risposta riuscita restituisce un WhatsAppTemplateList.

Schemi#

Error#

Error envelope returned for non-2xx responses.

Campo	Tipo	Obbligatorio	Descrizione
`error`	object	Sì

WhatsAppAnswerPolicy#

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

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

WhatsAppBoardRef#

Campo	Tipo	Obbligatorio	Descrizione
`name`	string	Sì
`trigger`	string	Sì	`trigger.whatsapp_message` or `trigger.whatsapp_team_reply`.

WhatsAppBound#

Campo	Tipo	Obbligatorio
`max`	integer	Sì
`min`	integer	Sì
`step`	integer	Sì

WhatsAppBoundsView#

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

WhatsAppClaim#

Campo	Tipo	Obbligatorio	Descrizione
`at`	string (date-time)	Sì
`by`	string	Sì

WhatsAppClosedDay#

Campo	Tipo	Obbligatorio	Descrizione
`date`	string	Sì
`window_id`	string	Sì

WhatsAppCoexView#

Campo	Tipo	Obbligatorio	Descrizione
`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.

Campo	Tipo	Obbligatorio	Descrizione
`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	Sì	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#

Campo	Tipo	Obbligatorio	Descrizione
`conversation_id`	string	Sì
`has_imported_history`	boolean	Sì	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	Sì	The business number, E.164.
`number_id`	string	Sì
`number_name`	string		The business number's verified name.
`phone`	string
`profile_name`	string
`user_id`	string
`window_open_until`	string (date-time)

WhatsAppContactConversationList#

Campo	Tipo	Obbligatorio	Descrizione
`items`	array of `WhatsAppContactConversation`	Sì

WhatsAppConversationPage#

Campo	Tipo	Obbligatorio	Descrizione
`items`	array of `WhatsAppConversationView`	Sì
`next_cursor`	string	Sì

WhatsAppConversationView#

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

Campo	Tipo	Descrizione
`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#

Campo	Tipo	Obbligatorio	Descrizione
`disclosure`	map of string	Sì	The default AI disclosure line per language; `{business}` stands for the number's verified name.

WhatsAppDisconnectView#

Campo	Tipo	Obbligatorio	Descrizione
`phone_number_id`	string	Sì
`token_deleted`	boolean	Sì	true when the account's token was deleted with it.
`unsubscribed`	boolean	Sì	true when this was the WhatsApp account's last number here and Meta confirmed the release.

WhatsAppDuration#

Campo	Tipo	Obbligatorio	Descrizione
`kind`	string	Sì	`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#

Campo	Tipo	Obbligatorio	Descrizione

WhatsAppHealthError#

Campo	Tipo	Obbligatorio
`entity_type`	string	Sì
`error_code`	integer	Sì
`error_description`	string	Sì
`possible_solution`	string	Sì

WhatsAppHealthView#

Campo	Tipo	Obbligatorio	Descrizione
`additional_info`	array of string	Sì
`can_send_message`	string	Sì	`AVAILABLE`, `LIMITED`, `BLOCKED`, or empty before the first read.
`checked_at`	string (date-time)		When the health was read.
`errors`	array of `WhatsAppHealthError`	Sì	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#

Campo	Tipo	Obbligatorio
`contacts_choice`	string	Sì
`contacts_imported`	integer	Sì
`contacts_matched`	integer	Sì
`contacts_state`	string	Sì
`deadline_at`	string (date-time)
`failure_code`	string
`finished_at`	string (date-time)
`history_choice`	string	Sì
`history_state`	string	Sì
`messages_imported`	integer	Sì
`messages_skipped`	integer	Sì
`onboarded_at`	string (date-time)
`phase`	integer	Sì
`progress`	integer	Sì
`state`	string	Sì

WhatsAppLinePatch#

Campo	Tipo	Obbligatorio	Descrizione
`enabled`	boolean	Sì	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#

Campo	Tipo	Obbligatorio	Descrizione
`enabled`	boolean	Sì	true when the line is sent.
`texts`	map of string	Sì	The line per BCP-47 language, at most 300 characters each.

WhatsAppLocation#

Campo	Tipo	Obbligatorio
`address`	string
`latitude`	number	Sì
`longitude`	number	Sì
`name`	string

WhatsAppMediaView#

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

WhatsAppMemoryPatch#

Campo	Tipo	Obbligatorio	Descrizione
`idle_close_min`	integer	Sì
`lookback_days`	integer	Sì
`recent_messages`	integer	Sì
`summary_enabled`	boolean		Leave it out to keep the stored value.

WhatsAppMemoryView#

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

WhatsAppMessagePage#

Campo	Tipo	Obbligatorio	Descrizione
`items`	array of `WhatsAppMessageView`	Sì
`next_cursor`	string	Sì

WhatsAppMessageView#

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

WhatsAppNumberList#

Campo	Tipo	Obbligatorio	Descrizione
`items`	array of `WhatsAppNumberView`	Sì

WhatsAppNumberPatch#

Campo	Tipo	Obbligatorio	Descrizione
`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.

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

WhatsAppOverride#

Campo	Tipo	Obbligatorio	Descrizione
`at`	string (date-time)	Sì
`by`	string	Sì
`kind`	string	Sì
`mode`	string	Sì
`until`	string (date-time)
`via`	string	Sì	`console`, `api` or `link`.

WhatsAppPauseRequest#

Campo	Tipo	Obbligatorio	Descrizione
`duration`	`WhatsAppDuration`	Sì	How long: `minutes`, `end_of_day`, `window_end`, `quiet_minutes` or `manual`.

WhatsAppPauseTrigger#

Campo	Tipo	Obbligatorio	Descrizione
`duration`	`WhatsAppDuration`	Sì
`enabled`	boolean	Sì

WhatsAppPauseTriggers#

Campo	Tipo	Obbligatorio
`console`	`WhatsAppPauseTrigger`	Sì
`handover`	`WhatsAppPauseTrigger`	Sì
`takeover`	`WhatsAppToggle`	Sì
`team_app`	`WhatsAppPauseTrigger`	Sì

WhatsAppPolicyLine#

Campo	Tipo	Obbligatorio	Descrizione
`enabled`	boolean	Sì
`texts`	map of string	Sì	The line per BCP-47 language, at most 300 characters each.

WhatsAppPolicyPreviewRequest#

Campo	Tipo	Obbligatorio	Descrizione
`policy`	`WhatsAppAnswerPolicy`	Sì	Who answers a number's WhatsApp messages, and when.

WhatsAppPolicyPut#

Campo	Tipo	Obbligatorio	Descrizione
`policy`	`WhatsAppAnswerPolicy`	Sì	Who answers a number's WhatsApp messages, and when.
`version`	integer	Sì	The version this edit was based on.

WhatsAppPolicySummary#

Campo	Tipo	Obbligatorio	Descrizione
`preset`	string	Sì	The preset that last filled the policy, or `custom`.
`version`	integer	Sì	The policy's version.
`windows`	integer	Sì	How many windows the policy has.

WhatsAppPolicyView#

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

WhatsAppPolicyWindow#

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

Campo	Tipo	Obbligatorio	Descrizione
`emoji`	string
`message_id`	string	Sì

WhatsAppReentry#

Campo	Tipo	Obbligatorio	Descrizione
`answer_pending`	boolean	Sì
`at`	string (date-time)
`minutes`	integer
`rule`	string	Sì	What brings the agent back first: `pause_end`, `team_silence`, `window_change`, `quiet` or `manual`.

WhatsAppReentryHours#

Campo	Tipo	Obbligatorio	Descrizione
`enabled`	boolean	Sì
`hours`	integer	Sì

WhatsAppReentryMinutes#

Campo	Tipo	Obbligatorio	Descrizione
`enabled`	boolean	Sì
`minutes`	integer	Sì

WhatsAppReentryPauseEnd#

Campo	Tipo	Obbligatorio	Descrizione
`answer_pending`	boolean	Sì
`enabled`	boolean	Sì

WhatsAppReentryRules#

Campo	Tipo	Obbligatorio
`never`	boolean	Sì
`pause_end`	`WhatsAppReentryPauseEnd`	Sì
`quiet`	`WhatsAppReentryHours`	Sì
`team_silence`	`WhatsAppReentryMinutes`	Sì
`window_change`	`WhatsAppToggle`	Sì

WhatsAppReplyRequest#

Campo	Tipo	Obbligatorio	Descrizione
`rep_name`	string		The name the conversation shows for the reply, at most 80 characters.
`text`	string	Sì	1 to 4,096 characters.

WhatsAppReplyView#

Campo	Tipo	Obbligatorio	Descrizione
`conversation`	`WhatsAppConversationView`	Sì
`message`	`WhatsAppMessageView`	Sì

WhatsAppResumeRequest#

Campo	Tipo	Obbligatorio	Descrizione
`hold`	`WhatsAppDuration`		Keep the agent answering until then: `minutes`, `end_of_day`, `window_end` or `manual`.

WhatsAppSchedule#

Campo	Tipo	Obbligatorio	Descrizione
`days`	array of `WhatsAppScheduleDay`	Sì

WhatsAppScheduleDay#

Campo	Tipo	Obbligatorio	Descrizione
`day`	string	Sì
`ranges`	array of `WhatsAppScheduleRange`

WhatsAppScheduleRange#

Campo	Tipo	Obbligatorio	Descrizione
`end`	string	Sì
`start`	string	Sì

WhatsAppSharedContact#

Campo	Tipo	Obbligatorio
`emails`	array of string
`name`	string	Sì
`org`	string
`phones`	array of string

WhatsAppStatus#

Campo	Tipo	Obbligatorio
`chip`	`WhatsAppStatusChip`	Sì
`claim`	`WhatsAppClaim`
`hand_seq`	integer	Sì
`override`	`WhatsAppOverride`
`policy_version`	integer	Sì
`quiet_minutes`	integer
`reason`	string	Sì
`reentry`	`WhatsAppReentry`
`state`	string	Sì
`unanswered`	integer	Sì
`until`	string (date-time)
`until_kind`	string
`waiting_for`	string
`window`	string	Sì
`window_id`	string	Sì
`window_mode`	string	Sì
`window_open_until`	string (date-time)

WhatsAppStatusChip#

Campo	Tipo	Obbligatorio
`key`	string	Sì
`params`	map of string	Sì
`tone`	string	Sì

WhatsAppSwitchRequest#

Campo	Tipo	Obbligatorio	Descrizione
`action`	string	Sì	`start` or `cancel`.

WhatsAppTemplateList#

Campo	Tipo	Obbligatorio	Descrizione
`items`	array of `WhatsAppTemplateView`	Sì
`synced_at`	string (date-time)		When the templates were last synced from Meta.
`truncated`	boolean	Sì	true when the account has more than 2,000 templates: filter by status.

WhatsAppTemplateRef#

Campo	Tipo	Obbligatorio	Descrizione
`language`	string	Sì
`name`	string	Sì

WhatsAppTemplateView#

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

WhatsAppToggle#

Campo	Tipo	Obbligatorio	Descrizione
`enabled`	boolean	Sì

WhatsAppTokenView#

Campo	Tipo	Obbligatorio	Descrizione
`expires_at`	string (date-time)		When the business token expires; absent when it does not.
`expiring`	boolean	Sì	true within 7 days of the expiry: connect again in the console.
`invalid`	boolean	Sì	true when the token no longer works: connect again in the console.

WhatsAppWeekChange#

Campo	Tipo	Obbligatorio
`at`	string (date-time)	Sì
`mode`	string	Sì
`window_id`	string	Sì

WhatsAppWeekDay#

Campo	Tipo	Obbligatorio	Descrizione
`day`	string	Sì
`segments`	array of `WhatsAppWeekSegment`	Sì

WhatsAppWeekNow#

Campo	Tipo	Obbligatorio
`local_time`	string	Sì
`mode`	string	Sì
`until`	string (date-time)
`window_id`	string	Sì

WhatsAppWeekPreview#

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

Campo	Tipo	Obbligatorio
`closed_days`	array of `WhatsAppClosedDay`	Sì
`days`	array of `WhatsAppWeekDay`	Sì
`next_changes`	array of `WhatsAppWeekChange`	Sì
`now`	`WhatsAppWeekNow`	Sì
`timezone`	string	Sì

WhatsAppWeekSegment#

Campo	Tipo	Obbligatorio	Descrizione
`agent_delay_s`	integer	Sì
`end`	string	Sì
`mode`	string	Sì	`agent`, `team_then_agent`, `team_only` or `agent_off`.
`start`	string	Sì
`team_wait_s`	integer
`window_id`	string	Sì
`window_kind`	string	Sì
`window_name`	string	Sì

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

Parametri

Risposte

Esempio di richiesta

GET /v1/integrations/whatsapp/config#

Parametri

Risposte

Esempio di richiesta

GET /v1/integrations/whatsapp/conversations#

Parametri

Risposte

Esempio di richiesta

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

Parametri

Risposte

Esempio di richiesta

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

Parametri

Corpo della richiesta

Risposte

Esempio di richiesta

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

Parametri

Risposte

Esempio di richiesta

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

Parametri

Risposte

Esempio di richiesta

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

Parametri

Corpo della richiesta

Risposte

Esempio di richiesta

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

Parametri

Corpo della richiesta

Risposte

Esempio di richiesta

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

Parametri

Corpo della richiesta

Risposte

Esempio di richiesta

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

Parametri

Corpo della richiesta

Risposte

Esempio di richiesta

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

Parametri

Risposte

Esempio di richiesta

GET /v1/integrations/whatsapp/numbers#

Risposte

Esempio di richiesta

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

Parametri

Risposte

Esempio di richiesta

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

Parametri

Risposte

Esempio di richiesta

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

Parametri

Corpo della richiesta

Risposte

Esempio di richiesta

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

Parametri

Risposte

Esempio di richiesta

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

Parametri

Corpo della richiesta

Risposte

Esempio di richiesta

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

Parametri

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