Create a COD confirmation
Requires a configured delivery time zone and follow-up texts for the exact language. Use an APPROVED, standard UTILITY template with no header or a text header and only the required quick-reply buttons. Parameters must match the template count/names. The confirmation template has exactly three buttons, in order: confirm, cancel, change time.
One accepted create consumes one monthly confirmation unit. Reference is required and not unique.
With an optional Idempotency-Key, repeated requests must match every value, treating equivalent phone number formats and uppercase/lowercase UUID characters as the same; named object key order does not matter. Completed repeats return the original acceptance without another send or quota unit.
Unknown query parameters are rejected. Unknown body fields are rejected. All examples use fictional values.
Responses
| Status | Meaning and codes |
|---|---|
| 202 | Accepted. Completion is asynchronous. |
| 401 | Problem Details. Codes: API_KEY_INVALID. |
| 404 | Problem Details. Codes: COD_SENDER_NOT_FOUND, COD_TEMPLATE_NOT_FOUND. |
| 409 | Problem Details. Codes: COD_NOT_CONFIGURED, COD_LANGUAGE_NOT_CONFIGURED, COD_SENDER_UNAVAILABLE, COD_TEMPLATE_NOT_USABLE, IDEMPOTENCY_KEY_REUSED. |
| 422 | Problem Details. Codes: DEVELOPER_INVALID_INPUT, COD_TEMPLATE_PARAMETERS_INVALID, RECIPIENT_BLOCKED. |
| 429 | Problem Details. Codes: RATE_LIMITED, COD_QUOTA_EXCEEDED. Retry-After: 1 is present only for RATE_LIMITED; quota errors do not include it. |
Success and handled error responses send Cache-Control: no-store and X-Correlation-ID (the resolved/generated UUID). Errors use application/problem+json and the reusable ProblemDetails schema below. Retry-After: 1 is sent only for RATE_LIMITED. Request examples read your key from a server environment variable; replace all fictional values.
Schemas and examples
ApiKeyAuthorizationBearer <token>Server-side API key. publicId is 12 lowercase base32 characters (a-z, 2-7); secret is 43 base64url characters from 32 random bytes. Use Authorization: Bearer <complete key>. The API key determines the workspace; requests cannot select another workspace. All public routes share 20 requests per second per key. See API-key authentication.
Idempotency-Key?stringOptional string of at most 128 characters. Empty string is accepted by validation; use a unique non-empty value per request. Save it and reuse it if you are unsure whether the request succeeded. See each operation for which values must match on repeated requests.
length <= 128X-Correlation-ID?stringOptional tracing ID. A UUID-shaped value is echoed in the response. Missing or invalid values are replaced with a generated UUID, not rejected.
application/json- body
to*stringMust be a valid phone number in international format with a leading +; it is normalized to E.164. Surrounding whitespace is trimmed.
1 <= lengthsenderId*stringThe Sender ID of a WhatsApp phone number in your workspace, shown in the dashboard under Developers > Overview (Senders) - not a Meta phone number ID.
uuidtemplate*parameters?reference*stringCaller order reference. Not unique.
1 <= length <= 128Accepted. Completion is asynchronous.
application/json- response
confirmationId*stringConfirmation UUID.
uuidstatus*stringAcceptance response; not the current answer state.
reference*stringCaller order reference.