Messages

API reference descriptions are provided in English to preserve the exact published contract.

GETList messagesmessages.list
POSTCreate a messagemessages.create
POSTCreate up to 1,000 messages with independent per-item admissionmessages.batch
GETFetch message batch countsmessages.batches.retrieve
POSTCancel up to 100 messagesmessages.bulkCancel
POSTIrreversibly redact up to 100 messages through a deletion requestmessages.bulkRedact
POSTPreflight a message without creating itmessages.preflight
GETLook up an original message submission without resending itmessages.submissions.retrieve
GETFetch a messagemessages.retrieve
DELETERedact and schedule removal of a messagemessages.delete
POSTCancel a message before provider submissionmessages.cancel
POSTMark an inbound WhatsApp message readmessages.read
POSTIrreversibly redact message contentmessages.redact
POSTSend a WhatsApp typing indicator and mark the inbound message readmessages.typing

List messages

GET/v1/accounts/{AC}/messages

messages.listSDK operation getV1AccountsByAcMessages

List messages, newest first. Filter by status, sender, recipient or time range; follow nextCursor to page.

Required scope: messages:read.Paginated

Parameters

limitinteger (1–100)query
cursorstring (max 2048 chars)query
statusstring (max 32 chars)query
fromstring (WA… SID)query
tostring (max 128 chars)query
contactSidstring (CT… SID)query
campaignSidstring (CP… SID)query
batchSidstring (MB… SID)query
directionenumquery
outboundinbound
createdAfterstring (date-time)query
createdBeforestring (date-time)query
tagstring (max 40 chars)query
templateSidstring (TM… SID)query
templateNamestring (max 512 chars)query
providerMessageIdstring (max 256 chars)query
sidsstring (max 3299 chars)query
sortenumquery
createdAt-createdAt

GET /v1/accounts/{AC}/messages

curl "https://api.staging.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/messages" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21"

Responses

Create a message

POST/v1/accounts/{AC}/messages

messages.createSDK operation postV1AccountsByAcMessages

Send one WhatsApp message. The request is accepted (202) once it is stored and admitted; delivery progress arrives as message.* webhook events and on the message itself. Send an Idempotency-Key header so a retry never sends twice. Outside the 24-hour customer service window only an approved template can be sent. A real Sandbox inbox reply requires conversationSid, its current composer claim, an admitted registered sender and currently verified recipient, an open service window and sponsored limits. That path supports immediate text only, without a customer-wallet charge; standalone real-test sends use the Real Test API.

Required scope: messages:send.Idempotency-Key required

Inbox and dashboard sessions

Alternatively, a normal tenant USER session may use messages:send on the exact inbox resolved from this resource. Actual inbox membership, tenant/subaccount visibility and per-operation checks still apply. This does not grant account-wide scopes, API-key permission, staff-delegation authority or platform access.

This reply alternative requires conversationSid and a valid composerClaimToken. from must be omitted or the exact conversation sender SID; sender pools and composer overrides require account-level authorization.

Request body

addressobject
Show 6 child attributes
- bodystring (max 1024 chars)Required
- countryenumRequired
  INSG
- savedAddressesobject[]
- subtype"address"
- validationErrorsobject
- valuesobject
carouselobject
Show 3 child attributes
- bodystring (max 1024 chars)Required
- cardsobject[]Required
- subtype"carousel"
catalogobject
Show 4 child attributes
- bodystring (max 1024 chars)Required
- catalogIdstring (max 128 chars)Required
- footerstring (max 60 chars)
- thumbnailProductRetailerIdstring (max 256 chars)
categoryenum
Derived from the template when absent; must match it when present
authenticationutilitymarketingservice
composerClaimTokenstring (uuid)
composerOverrideReasonstring (max 1000 chars)
contactSidstring (CT… SID)
Contact SID; addresses an existing contact directly
contactsobject
Show 1 child attributes
- contactsobject[]Required
contentSidstring (HX… SID)
Reusable content SID; alternative to type/template
contextobject
Show 2 child attributes
- providerMessageIdstring (max 256 chars)
- replyToMessageIdstring (SM… SID)
  Message SID
conversationSidstring (CO… SID)
Conversation SID for an agent inbox reply
defaultCountrystring (pattern ^[A-Za-z]{2}$)
ISO 3166-1 alpha-2 country used to read a national phone number (NG reads 08031234567 as +2348031234567). Without it the number must start with + or 00.
deferIfCappedboolean
Defer marketing sends until a recipient cap clears
flowobject
Show 6 child attributes
- bodystring (max 1024 chars)Required
- ctaTextstring (max 20 chars)Required
- flowSidstring (FL… SID)Required
  Published Flow SID
- actionenum
  navigatedata_exchange
- dataobject
- screenstring (max 128 chars)
fromstring (WA… SID)
Sender SID
interactiveobject
locationobject
Show 4 child attributes
- latitudenumber (-90–90)Required
- longitudenumber (-180–180)Required
- addressstring (max 1000 chars)
- namestring (max 1000 chars)
mediaobject
Show 4 child attributes
- sidstring (ME… SID)Required
  Media SID; must be READY
- captionstring (max 1024 chars)
- filenamestring (max 255 chars)
- voiceboolean
metadataobject
priorityenum
P0P1P2P3
productobject
Show 4 child attributes
- catalogIdstring (max 128 chars)Required
- productRetailerIdstring (max 256 chars)Required
- bodystring (max 1024 chars)
- footerstring (max 60 chars)
productListobject
Show 6 child attributes
- catalogIdstring (max 128 chars)Required
- headerstring (max 60 chars)Required
- sectionsobject[]Required
- bodystring (max 1024 chars)
- footerstring (max 60 chars)
- subtype"product_list"
reactionobject
Show 2 child attributes
- emojistring (max 16 chars)Required
- targetMessageIdstring (max 256 chars)Required
recipientobject
Show 2 child attributes
- identifierTypeenumRequired
  phone_e164bsuidusername
- valuestring (max 64 chars)Required
sendAtstring (date-time)
RFC 3339; ≤ 35 days ahead
senderPoolSidstring (SP… SID)
Sender pool SID
statusCallbackSidstring (WH… SID)
Verified webhook endpoint SID; alternative to statusCallbackUrl
statusCallbackUrlstring (uri, max 2048 chars)
tagsstring (max 40 chars)[]
templateobject
Show 3 child attributes
- languagestring (max 16 chars)Required
- namestring (max 512 chars)Required
- componentsobject[]
textobject
Show 2 child attributes
- bodystring (max 4096 chars)Required
- previewUrlboolean
tostring (max 32 chars)
E.164 recipient (whatsapp: prefix accepted and stripped)
transportenum
cloud_apimarketing_messages
transportOptionsobject
Show 1 child attributes
- ttlSecondsinteger (43200–2592000)
typeenum
texttemplateimagevideoaudiodocumentstickerlocationcontactsreactioninteractiveproductcatalogflowproduct_listaddresscarousel
validityPeriodSecondsinteger (30–2592000)
variablesobject

POST /v1/accounts/{AC}/messages

curl -X POST "https://api.staging.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/messages" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "'"$TOUTYE_SANDBOX_SENDER_SID"'",
  "to": "+15550000001",
  "type": "text",
  "text": {
    "body": "Hello from the Toutye sandbox"
  }
}'

Responses

Create up to 1,000 messages with independent per-item admission

POST/v1/accounts/{AC}/messages/batch

messages.batchSDK operation postV1AccountsByAcMessagesBatch

Send up to 1,000 messages in one request. Each item is admitted or refused on its own; the response reports each item's outcome and a batch SID to follow progress.

Required scope: messages:send.Idempotency-Key required

Request body

messagesobject[]Required

POST /v1/accounts/{AC}/messages/batch

curl -X POST "https://api.staging.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/messages/batch" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": []
}'

Responses

Fetch message batch counts

GET/v1/accounts/{AC}/messages/batches/{MB}

messages.batches.retrieveSDK operation getV1AccountsByAcMessagesBatchesByMb

Fetch how many items of a batch were accepted, refused, sent and delivered.

Required scope: messages:read.

Parameters

MBstring (MB… SID)Required

GET /v1/accounts/{AC}/messages/batches/{MB}

curl "https://api.staging.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/messages/batches/MB..." \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21"

Responses

Cancel up to 100 messages

POST/v1/accounts/{AC}/messages/bulk-cancel

messages.bulkCancelSDK operation postV1AccountsByAcMessagesBulkCancel

Required scope: messages:cancel.Idempotency-Key required

Request body

messageSidsstring (SM… SID)[]Required
reasonstring (max 1000 chars)Required
stepUpTokenstring (max 256 chars)

POST /v1/accounts/{AC}/messages/bulk-cancel

curl -X POST "https://api.staging.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/messages/bulk-cancel" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "messageSids": "SM...",
  "reason": "string"
}'

Responses

Irreversibly redact up to 100 messages through a deletion request

POST/v1/accounts/{AC}/messages/bulk-redact

messages.bulkRedactSDK operation postV1AccountsByAcMessagesBulkRedact

Required scope: messages:redact.Idempotency-Key required

Request body

messageSidsstring (SM… SID)[]Required
reasonstring (max 1000 chars)Required
stepUpTokenstring (max 256 chars)

POST /v1/accounts/{AC}/messages/bulk-redact

curl -X POST "https://api.staging.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/messages/bulk-redact" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "messageSids": "SM...",
  "reason": "string"
}'

Responses

Preflight a message without creating it

POST/v1/accounts/{AC}/messages/preflight

messages.preflightSDK operation postV1AccountsByAcMessagesPreflight

Check whether a message would be accepted, and what it would cost, without creating it. Takes the same body as sending. Real Sandbox inbox text replies check the verified recipient, composer claim, service window, consent and sponsored limits; no real message or sponsored reservation is committed by preflight.

Required scope: messages:send.Idempotency-Key required

Inbox and dashboard sessions

Request body

addressobject
Show 6 child attributes
- bodystring (max 1024 chars)Required
- countryenumRequired
  INSG
- savedAddressesobject[]
- subtype"address"
- validationErrorsobject
- valuesobject
carouselobject
Show 3 child attributes
- bodystring (max 1024 chars)Required
- cardsobject[]Required
- subtype"carousel"
catalogobject
Show 4 child attributes
- bodystring (max 1024 chars)Required
- catalogIdstring (max 128 chars)Required
- footerstring (max 60 chars)
- thumbnailProductRetailerIdstring (max 256 chars)
categoryenum
Derived from the template when absent; must match it when present
authenticationutilitymarketingservice
composerClaimTokenstring (uuid)
composerOverrideReasonstring (max 1000 chars)
contactSidstring (CT… SID)
Contact SID; addresses an existing contact directly
contactsobject
Show 1 child attributes
- contactsobject[]Required
contentSidstring (HX… SID)
Reusable content SID; alternative to type/template
contextobject
Show 2 child attributes
- providerMessageIdstring (max 256 chars)
- replyToMessageIdstring (SM… SID)
  Message SID
conversationSidstring (CO… SID)
Conversation SID for an agent inbox reply
defaultCountrystring (pattern ^[A-Za-z]{2}$)
ISO 3166-1 alpha-2 country used to read a national phone number (NG reads 08031234567 as +2348031234567). Without it the number must start with + or 00.
deferIfCappedboolean
Defer marketing sends until a recipient cap clears
flowobject
Show 6 child attributes
- bodystring (max 1024 chars)Required
- ctaTextstring (max 20 chars)Required
- flowSidstring (FL… SID)Required
  Published Flow SID
- actionenum
  navigatedata_exchange
- dataobject
- screenstring (max 128 chars)
fromstring (WA… SID)
Sender SID
interactiveobject
locationobject
Show 4 child attributes
- latitudenumber (-90–90)Required
- longitudenumber (-180–180)Required
- addressstring (max 1000 chars)
- namestring (max 1000 chars)
mediaobject
Show 4 child attributes
- sidstring (ME… SID)Required
  Media SID; must be READY
- captionstring (max 1024 chars)
- filenamestring (max 255 chars)
- voiceboolean
metadataobject
priorityenum
P0P1P2P3
productobject
Show 4 child attributes
- catalogIdstring (max 128 chars)Required
- productRetailerIdstring (max 256 chars)Required
- bodystring (max 1024 chars)
- footerstring (max 60 chars)
productListobject
Show 6 child attributes
- catalogIdstring (max 128 chars)Required
- headerstring (max 60 chars)Required
- sectionsobject[]Required
- bodystring (max 1024 chars)
- footerstring (max 60 chars)
- subtype"product_list"
reactionobject
Show 2 child attributes
- emojistring (max 16 chars)Required
- targetMessageIdstring (max 256 chars)Required
recipientobject
Show 2 child attributes
- identifierTypeenumRequired
  phone_e164bsuidusername
- valuestring (max 64 chars)Required
sendAtstring (date-time)
RFC 3339; ≤ 35 days ahead
senderPoolSidstring (SP… SID)
Sender pool SID
statusCallbackSidstring (WH… SID)
Verified webhook endpoint SID; alternative to statusCallbackUrl
statusCallbackUrlstring (uri, max 2048 chars)
tagsstring (max 40 chars)[]
templateobject
Show 3 child attributes
- languagestring (max 16 chars)Required
- namestring (max 512 chars)Required
- componentsobject[]
textobject
Show 2 child attributes
- bodystring (max 4096 chars)Required
- previewUrlboolean
tostring (max 32 chars)
E.164 recipient (whatsapp: prefix accepted and stripped)
transportenum
cloud_apimarketing_messages
transportOptionsobject
Show 1 child attributes
- ttlSecondsinteger (43200–2592000)
typeenum
texttemplateimagevideoaudiodocumentstickerlocationcontactsreactioninteractiveproductcatalogflowproduct_listaddresscarousel
validityPeriodSecondsinteger (30–2592000)
variablesobject

POST /v1/accounts/{AC}/messages/preflight

curl -X POST "https://api.staging.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/messages/preflight" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)"

Responses

Look up an original message submission without resending it

GET/v1/accounts/{AC}/messages/submissions/{submissionKey}

messages.submissions.retrieveSDK operation getV1AccountsByAcMessagesSubmissionsBySubmissionkey

Read-only reconciliation. Unknown includes missing, expired and unfinished records and never proves that a message was not accepted.

Required scope: messages:read.

Parameters

submissionKeystring (pattern ^[0-9a-fA-F-]{36}$)Required

GET /v1/accounts/{AC}/messages/submissions/{submissionKey}

curl "https://api.staging.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/messages/submissions/submissionKey..." \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21"

Responses

Fetch a message

GET/v1/accounts/{AC}/messages/{SM}

messages.retrieveSDK operation getV1AccountsByAcMessagesBySm

Fetch one message with its current status, the provider's delivery timeline and, once settled, its charge.

Required scope: messages:read.

Parameters

SMstring (SM… SID)Required
Message SID

GET /v1/accounts/{AC}/messages/{SM}

curl "https://api.staging.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/messages/SM..." \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21"

Responses

Redact and schedule removal of a message

DELETE/v1/accounts/{AC}/messages/{SM}

messages.deleteSDK operation deleteV1AccountsByAcMessagesBySm

Required scope: messages:redact.

Parameters

SMstring (SM… SID)Required
Message SID

DELETE /v1/accounts/{AC}/messages/{SM}

curl -X DELETE "https://api.staging.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/messages/SM..." \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21"

Responses

Cancel a message before provider submission

POST/v1/accounts/{AC}/messages/{SM}/cancel

messages.cancelSDK operation postV1AccountsByAcMessagesBySmCancel

Cancel a message that has not yet been handed to WhatsApp. A message already submitted cannot be recalled.

Required scope: messages:cancel.Idempotency-Key required

Parameters

SMstring (SM… SID)Required
Message SID

POST /v1/accounts/{AC}/messages/{SM}/cancel

curl -X POST "https://api.staging.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/messages/SM.../cancel" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)"

Responses

Mark an inbound WhatsApp message read

POST/v1/accounts/{AC}/messages/{SM}/read

messages.readSDK operation postV1AccountsByAcMessagesBySmRead

Mark an inbound message as read, which shows the blue ticks to the sender.

Required scope: messages:write.Idempotency-Key required

Parameters

SMstring (SM… SID)Required
Message SID

POST /v1/accounts/{AC}/messages/{SM}/read

curl -X POST "https://api.staging.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/messages/SM.../read" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)"

Responses

Irreversibly redact message content

POST/v1/accounts/{AC}/messages/{SM}/redact

messages.redactSDK operation postV1AccountsByAcMessagesBySmRedact

: requires a reason, recorded on the audit entry, and a fresh step-up grant for MESSAGE_REDACT, consumed in the same transaction as the redaction.

Required scope: messages:redact.Idempotency-Key required

Parameters

SMstring (SM… SID)Required
Message SID

Request body

reasonstring (max 1000 chars)Required
stepUpTokenstring (max 256 chars)Required

POST /v1/accounts/{AC}/messages/{SM}/redact

curl -X POST "https://api.staging.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/messages/SM.../redact" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string",
  "stepUpToken": "string"
}'

Responses

Send a WhatsApp typing indicator and mark the inbound message read

POST/v1/accounts/{AC}/messages/{SM}/typing

messages.typingSDK operation postV1AccountsByAcMessagesBySmTyping

Required scope: messages:write.Idempotency-Key required

Parameters

SMstring (SM… SID)Required
Message SID

POST /v1/accounts/{AC}/messages/{SM}/typing

curl -X POST "https://api.staging.toutye.com/v1/accounts/$TOUTYE_ACCOUNT_SID/messages/SM.../typing" \
  -H "Authorization: Bearer $TOUTYE_API_KEY" \
  -H "Toutye-Version: 2026-08-21" \
  -H "Idempotency-Key: $(uuidgen)"

Responses