{
"id": "<string>",
"wabaId": "whatsapp-business-account-id",
"from": "+16315551111",
"wamid": "wamid.BgNODYxN...",
"to": "+16315551111",
"recipient": "US.1234",
"recipientUserId": "US.1234",
"toUserId": "US.1234",
"parentRecipientUserId": "US.ENT.1234",
"toParentUserId": "US.ENT.1234",
"customerProfile": {
"name": "John",
"username": "john_doe"
},
"conversation": {
"id": "<string>",
"type": "FREE_ENTRY",
"originType": "referral_conversion",
"expireTime": "2022-06-01T12:00:00.000Z"
},
"type": "template",
"template": {
"name": "sample_whatsapp_template",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "header",
"sub_type": "quick_reply",
"index": 4,
"parameters": [
{
"type": "text",
"text": "<string>",
"payload": "<string>",
"coupon_code": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"gif": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"video": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"document": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"limited_time_offer": {
"expiration_time_ms": "1698562800000"
},
"action": {
"thumbnail_product_retailer_id": "2lc20305pt",
"sections": [
{
"title": "<string>",
"product_items": [
{
"product_retailer_id": "<string>"
}
]
}
],
"flow_token": "<string>",
"flow_action_data": {},
"order_details": {
"currency": "<string>",
"order": {
"status": "pending",
"type": "<string>",
"catalog_id": "<string>",
"items": [
{
"name": "<string>",
"amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"quantity": 123,
"retailer_id": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"sale_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"country_of_origin": "<string>",
"importer_name": "<string>",
"importer_address": "<string>"
}
],
"subtotal": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"tax": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"shipping": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"discount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"expiration": {
"timestamp": "1727438564",
"description": "<string>"
},
"description": "<string>"
},
"reference_id": "<string>",
"total_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"type": "<string>",
"payment_settings": [
{
"type": "payment_gateway",
"payment_gateway": {
"type": "billdesk",
"configuration_name": "<string>",
"billdesk": {
"additional_info1": "<string>",
"additional_info2": "<string>",
"additional_info3": "<string>",
"additional_info4": "<string>",
"additional_info5": "<string>",
"additional_info6": "<string>",
"additional_info7": "<string>"
},
"payu": {
"udf1": "<string>",
"udf2": "<string>",
"udf3": "<string>",
"udf4": "<string>"
},
"razorpay": {
"receipt": "<string>",
"notes": {}
},
"zaakpay": {
"extra1": "<string>",
"extra2": "<string>"
}
}
}
]
}
},
"order_status": {
"reference_id": "<string>",
"order": {
"status": "pending",
"type": "<string>",
"catalog_id": "<string>",
"items": [
{
"name": "<string>",
"amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"quantity": 123,
"retailer_id": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"sale_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"country_of_origin": "<string>",
"importer_name": "<string>",
"importer_address": "<string>"
}
],
"subtotal": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"tax": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"shipping": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"discount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"expiration": {
"timestamp": "1727438564",
"description": "<string>"
},
"description": "<string>"
}
},
"location": {
"latitude": 123,
"longitude": 123,
"name": "<string>",
"address": "<string>"
},
"group_id": "120363345678901234@g.us"
}
],
"cards": [
{
"card_index": 4,
"components": [
{
"type": "header",
"sub_type": "quick_reply",
"index": 4,
"parameters": [
{
"type": "text",
"text": "<string>",
"payload": "<string>",
"coupon_code": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"gif": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"video": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"document": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"limited_time_offer": {
"expiration_time_ms": "1698562800000"
},
"action": {
"thumbnail_product_retailer_id": "2lc20305pt",
"sections": [
{
"title": "<string>",
"product_items": [
{
"product_retailer_id": "<string>"
}
]
}
],
"flow_token": "<string>",
"flow_action_data": {},
"order_details": {
"currency": "<string>",
"order": {
"status": "pending",
"type": "<string>",
"catalog_id": "<string>",
"items": [
{
"name": "<string>",
"amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"quantity": 123,
"retailer_id": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"sale_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"country_of_origin": "<string>",
"importer_name": "<string>",
"importer_address": "<string>"
}
],
"subtotal": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"tax": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"shipping": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"discount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"expiration": {
"timestamp": "1727438564",
"description": "<string>"
},
"description": "<string>"
},
"reference_id": "<string>",
"total_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"type": "<string>",
"payment_settings": [
{
"type": "payment_gateway",
"payment_gateway": {
"type": "billdesk",
"configuration_name": "<string>",
"billdesk": {
"additional_info1": "<string>",
"additional_info2": "<string>",
"additional_info3": "<string>",
"additional_info4": "<string>",
"additional_info5": "<string>",
"additional_info6": "<string>",
"additional_info7": "<string>"
},
"payu": {
"udf1": "<string>",
"udf2": "<string>",
"udf3": "<string>",
"udf4": "<string>"
},
"razorpay": {
"receipt": "<string>",
"notes": {}
},
"zaakpay": {
"extra1": "<string>",
"extra2": "<string>"
}
}
}
]
}
},
"order_status": {
"reference_id": "<string>",
"order": {
"status": "pending",
"type": "<string>",
"catalog_id": "<string>",
"items": [
{
"name": "<string>",
"amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"quantity": 123,
"retailer_id": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"sale_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"country_of_origin": "<string>",
"importer_name": "<string>",
"importer_address": "<string>"
}
],
"subtotal": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"tax": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"shipping": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"discount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"expiration": {
"timestamp": "1727438564",
"description": "<string>"
},
"description": "<string>"
}
},
"location": {
"latitude": 123,
"longitude": 123,
"name": "<string>",
"address": "<string>"
},
"group_id": "120363345678901234@g.us"
}
]
}
]
}
]
}
]
},
"text": {
"body": "<string>",
"preview_url": true
},
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"video": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"audio": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"document": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"sticker": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"location": {
"latitude": 123,
"longitude": 123,
"name": "<string>",
"address": "<string>"
},
"interactive": {
"type": "button",
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"title": "<string>",
"id": "<string>"
}
}
],
"button": "<string>",
"catalog_id": "<string>",
"product_retailer_id": "<string>",
"sections": [
{
"title": "<string>",
"rows": [
{
"id": "<string>",
"title": "<string>",
"description": "<string>"
}
],
"product_items": [
{
"product_retailer_id": "<string>"
}
]
}
],
"name": "cta_url",
"parameters": {
"display_text": "See Docs",
"url": "https://developers.facebook.com/docs/whatsapp",
"thumbnail_product_retailer_id": "<string>",
"flow_message_version": "3",
"flow_token": "<string>",
"flow_id": "<string>",
"flow_name": "<string>",
"flow_cta": "Open flow!",
"flow_action": "navigate",
"flow_action_payload": {
"screen": "<string>",
"data": {}
},
"reference_id": "<string>",
"type": "digital-goods",
"beneficiaries": [
{
"name": "<string>",
"address_line1": "<string>",
"city": "<string>",
"state": "<string>",
"country": "<string>",
"postal_code": "<string>",
"address_line2": "<string>"
}
],
"currency": "INR",
"total_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"order": {
"status": "pending",
"type": "<string>",
"catalog_id": "<string>",
"items": [
{
"name": "<string>",
"amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"quantity": 123,
"retailer_id": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"sale_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"country_of_origin": "<string>",
"importer_name": "<string>",
"importer_address": "<string>"
}
],
"subtotal": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"tax": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"shipping": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"discount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"expiration": {
"timestamp": "1727438564",
"description": "<string>"
},
"description": "<string>"
},
"payment_settings": [
{
"type": "payment_gateway",
"payment_gateway": {
"type": "billdesk",
"configuration_name": "<string>",
"billdesk": {
"additional_info1": "<string>",
"additional_info2": "<string>",
"additional_info3": "<string>",
"additional_info4": "<string>",
"additional_info5": "<string>",
"additional_info6": "<string>",
"additional_info7": "<string>"
},
"payu": {
"udf1": "<string>",
"udf2": "<string>",
"udf3": "<string>",
"udf4": "<string>"
},
"razorpay": {
"receipt": "<string>",
"notes": {}
},
"zaakpay": {
"extra1": "<string>",
"extra2": "<string>"
}
}
}
]
},
"cards": [
{
"card_index": 4,
"type": "cta_url",
"header": {
"type": "image",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>"
},
"video": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>"
}
},
"action": {
"name": "cta_url",
"parameters": {
"display_text": "See Docs",
"url": "https://developers.facebook.com/docs/whatsapp"
},
"buttons": [
{
"type": "quick_reply",
"quick_reply": {
"title": "<string>",
"id": "<string>"
}
}
]
},
"body": {
"text": "<string>"
}
}
]
},
"body": {
"text": "<string>"
},
"header": {
"type": "text",
"text": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>"
},
"video": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>"
},
"document": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>"
}
},
"footer": {
"text": "<string>"
}
},
"contacts": [
{
"name": {
"formatted_name": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"middle_name": "<string>",
"suffix": "<string>",
"prefix": "<string>"
},
"addresses": [
{
"street": "<string>",
"city": "<string>",
"state": "<string>",
"zip": "<string>",
"country": "<string>",
"country_code": "<string>",
"type": "WORK"
}
],
"birthday": "2022-09-27",
"emails": [
{
"email": "<string>",
"type": "WORK"
}
],
"org": {
"company": "<string>",
"department": "<string>",
"title": "<string>"
},
"phones": [
{
"phone": "<string>",
"type": "<string>",
"wa_id": "<string>"
}
],
"urls": [
{
"url": "<string>",
"type": "<string>"
}
],
"vcard": "<string>",
"origin": "contact_request"
}
],
"reaction": {
"message_id": "wamid.BgNODYxN...",
"emoji": "<string>"
},
"context": {
"message_id": "wamid.BgNODYxN..."
},
"externalId": "<string>",
"category": "utility",
"ttlSeconds": 600,
"status": "accepted",
"errorCode": "INTERNAL_SERVER_ERROR",
"errorMessage": "<string>",
"createTime": "2022-06-01T12:00:00.000Z",
"updateTime": "2022-06-01T12:00:00.000Z",
"sendTime": "2022-06-01T12:00:00.000Z",
"deliverTime": "2022-06-01T12:00:00.000Z",
"readTime": "2022-06-01T12:00:00.000Z",
"totalPrice": 0.05,
"currency": "USD",
"regionCode": "US",
"pricingCategory": "referral_conversion",
"pricingModel": "PMP",
"pricingType": "regular",
"whatsappApiError": {
"message": "HSM Template creation failed",
"code": 200002,
"type": "OAuthException",
"is_transient": false,
"error_subcode": 2388109,
"error_user_msg": "This message template cannot be created.",
"error_user_title": "Message Cannot Be Submitted",
"fbtrace_id": "AVGjJ7ia2zJkrHG",
"error_data": "<string>"
},
"bizType": "whatsapp",
"verificationId": "VERIFICATION-ID"
}{
"error": {
"status": 404,
"code": "NOT_FOUND",
"message": "The requested resource does not exist.",
"target": "",
"docUrl": "",
"requestId": "req_1KjtKI80IKoaJNa6n6p",
"whatsappApiError": {
"message": "HSM Template creation failed",
"code": 200002,
"type": "OAuthException",
"is_transient": false,
"error_subcode": 2388109,
"error_user_msg": "This message template cannot be created.",
"error_user_title": "Message Cannot Be Submitted",
"fbtrace_id": "AVGjJ7ia2zJkrHG",
"error_data": "<string>"
},
"metaBusinessAgentApiError": {
"title": "<string>",
"detail": "<string>",
"type": "<string>",
"status": 123,
"requestId": "<string>"
}
}
}{
"error": {
"status": 404,
"code": "NOT_FOUND",
"message": "The requested resource does not exist.",
"target": "",
"docUrl": "",
"requestId": "req_1KjtKI80IKoaJNa6n6p",
"whatsappApiError": {
"message": "HSM Template creation failed",
"code": 200002,
"type": "OAuthException",
"is_transient": false,
"error_subcode": 2388109,
"error_user_msg": "This message template cannot be created.",
"error_user_title": "Message Cannot Be Submitted",
"fbtrace_id": "AVGjJ7ia2zJkrHG",
"error_data": "<string>"
},
"metaBusinessAgentApiError": {
"title": "<string>",
"detail": "<string>",
"type": "<string>",
"status": 123,
"requestId": "<string>"
}
}
}{
"error": {
"status": 404,
"code": "NOT_FOUND",
"message": "The requested resource does not exist.",
"target": "",
"docUrl": "",
"requestId": "req_1KjtKI80IKoaJNa6n6p",
"whatsappApiError": {
"message": "HSM Template creation failed",
"code": 200002,
"type": "OAuthException",
"is_transient": false,
"error_subcode": 2388109,
"error_user_msg": "This message template cannot be created.",
"error_user_title": "Message Cannot Be Submitted",
"fbtrace_id": "AVGjJ7ia2zJkrHG",
"error_data": "<string>"
},
"metaBusinessAgentApiError": {
"title": "<string>",
"detail": "<string>",
"type": "<string>",
"status": 123,
"requestId": "<string>"
}
}
}WhatsApp Messages
Send a message directly
Sends an outbound WhatsApp message directly.
The message is submitted to the WhatsApp Business API synchronously. Typically used for sending OTP and instant messages.
For endpoint selection, status synchronization, safe retries, and production controls, see WhatsApp Messages API best practices.
For custom utility content or template conversion, see Utility Direct Send. Utility Direct Send is in public beta and requires no allowlist or access application.
The response body field error.whatsappApiError is included if we tried to request the WhatsApp Business API and got an error response.
POST
https://api.ycloud.com/v2
/
whatsapp
/
messages
/
sendDirectly
{
"id": "<string>",
"wabaId": "whatsapp-business-account-id",
"from": "+16315551111",
"wamid": "wamid.BgNODYxN...",
"to": "+16315551111",
"recipient": "US.1234",
"recipientUserId": "US.1234",
"toUserId": "US.1234",
"parentRecipientUserId": "US.ENT.1234",
"toParentUserId": "US.ENT.1234",
"customerProfile": {
"name": "John",
"username": "john_doe"
},
"conversation": {
"id": "<string>",
"type": "FREE_ENTRY",
"originType": "referral_conversion",
"expireTime": "2022-06-01T12:00:00.000Z"
},
"type": "template",
"template": {
"name": "sample_whatsapp_template",
"language": {
"code": "en",
"policy": "deterministic"
},
"components": [
{
"type": "header",
"sub_type": "quick_reply",
"index": 4,
"parameters": [
{
"type": "text",
"text": "<string>",
"payload": "<string>",
"coupon_code": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"gif": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"video": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"document": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"limited_time_offer": {
"expiration_time_ms": "1698562800000"
},
"action": {
"thumbnail_product_retailer_id": "2lc20305pt",
"sections": [
{
"title": "<string>",
"product_items": [
{
"product_retailer_id": "<string>"
}
]
}
],
"flow_token": "<string>",
"flow_action_data": {},
"order_details": {
"currency": "<string>",
"order": {
"status": "pending",
"type": "<string>",
"catalog_id": "<string>",
"items": [
{
"name": "<string>",
"amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"quantity": 123,
"retailer_id": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"sale_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"country_of_origin": "<string>",
"importer_name": "<string>",
"importer_address": "<string>"
}
],
"subtotal": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"tax": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"shipping": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"discount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"expiration": {
"timestamp": "1727438564",
"description": "<string>"
},
"description": "<string>"
},
"reference_id": "<string>",
"total_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"type": "<string>",
"payment_settings": [
{
"type": "payment_gateway",
"payment_gateway": {
"type": "billdesk",
"configuration_name": "<string>",
"billdesk": {
"additional_info1": "<string>",
"additional_info2": "<string>",
"additional_info3": "<string>",
"additional_info4": "<string>",
"additional_info5": "<string>",
"additional_info6": "<string>",
"additional_info7": "<string>"
},
"payu": {
"udf1": "<string>",
"udf2": "<string>",
"udf3": "<string>",
"udf4": "<string>"
},
"razorpay": {
"receipt": "<string>",
"notes": {}
},
"zaakpay": {
"extra1": "<string>",
"extra2": "<string>"
}
}
}
]
}
},
"order_status": {
"reference_id": "<string>",
"order": {
"status": "pending",
"type": "<string>",
"catalog_id": "<string>",
"items": [
{
"name": "<string>",
"amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"quantity": 123,
"retailer_id": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"sale_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"country_of_origin": "<string>",
"importer_name": "<string>",
"importer_address": "<string>"
}
],
"subtotal": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"tax": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"shipping": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"discount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"expiration": {
"timestamp": "1727438564",
"description": "<string>"
},
"description": "<string>"
}
},
"location": {
"latitude": 123,
"longitude": 123,
"name": "<string>",
"address": "<string>"
},
"group_id": "120363345678901234@g.us"
}
],
"cards": [
{
"card_index": 4,
"components": [
{
"type": "header",
"sub_type": "quick_reply",
"index": 4,
"parameters": [
{
"type": "text",
"text": "<string>",
"payload": "<string>",
"coupon_code": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"gif": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"video": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"document": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"limited_time_offer": {
"expiration_time_ms": "1698562800000"
},
"action": {
"thumbnail_product_retailer_id": "2lc20305pt",
"sections": [
{
"title": "<string>",
"product_items": [
{
"product_retailer_id": "<string>"
}
]
}
],
"flow_token": "<string>",
"flow_action_data": {},
"order_details": {
"currency": "<string>",
"order": {
"status": "pending",
"type": "<string>",
"catalog_id": "<string>",
"items": [
{
"name": "<string>",
"amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"quantity": 123,
"retailer_id": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"sale_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"country_of_origin": "<string>",
"importer_name": "<string>",
"importer_address": "<string>"
}
],
"subtotal": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"tax": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"shipping": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"discount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"expiration": {
"timestamp": "1727438564",
"description": "<string>"
},
"description": "<string>"
},
"reference_id": "<string>",
"total_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"type": "<string>",
"payment_settings": [
{
"type": "payment_gateway",
"payment_gateway": {
"type": "billdesk",
"configuration_name": "<string>",
"billdesk": {
"additional_info1": "<string>",
"additional_info2": "<string>",
"additional_info3": "<string>",
"additional_info4": "<string>",
"additional_info5": "<string>",
"additional_info6": "<string>",
"additional_info7": "<string>"
},
"payu": {
"udf1": "<string>",
"udf2": "<string>",
"udf3": "<string>",
"udf4": "<string>"
},
"razorpay": {
"receipt": "<string>",
"notes": {}
},
"zaakpay": {
"extra1": "<string>",
"extra2": "<string>"
}
}
}
]
}
},
"order_status": {
"reference_id": "<string>",
"order": {
"status": "pending",
"type": "<string>",
"catalog_id": "<string>",
"items": [
{
"name": "<string>",
"amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"quantity": 123,
"retailer_id": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"sale_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"country_of_origin": "<string>",
"importer_name": "<string>",
"importer_address": "<string>"
}
],
"subtotal": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"tax": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"shipping": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"discount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"expiration": {
"timestamp": "1727438564",
"description": "<string>"
},
"description": "<string>"
}
},
"location": {
"latitude": 123,
"longitude": 123,
"name": "<string>",
"address": "<string>"
},
"group_id": "120363345678901234@g.us"
}
]
}
]
}
]
}
]
},
"text": {
"body": "<string>",
"preview_url": true
},
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"video": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"audio": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"document": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"sticker": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"location": {
"latitude": 123,
"longitude": 123,
"name": "<string>",
"address": "<string>"
},
"interactive": {
"type": "button",
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"title": "<string>",
"id": "<string>"
}
}
],
"button": "<string>",
"catalog_id": "<string>",
"product_retailer_id": "<string>",
"sections": [
{
"title": "<string>",
"rows": [
{
"id": "<string>",
"title": "<string>",
"description": "<string>"
}
],
"product_items": [
{
"product_retailer_id": "<string>"
}
]
}
],
"name": "cta_url",
"parameters": {
"display_text": "See Docs",
"url": "https://developers.facebook.com/docs/whatsapp",
"thumbnail_product_retailer_id": "<string>",
"flow_message_version": "3",
"flow_token": "<string>",
"flow_id": "<string>",
"flow_name": "<string>",
"flow_cta": "Open flow!",
"flow_action": "navigate",
"flow_action_payload": {
"screen": "<string>",
"data": {}
},
"reference_id": "<string>",
"type": "digital-goods",
"beneficiaries": [
{
"name": "<string>",
"address_line1": "<string>",
"city": "<string>",
"state": "<string>",
"country": "<string>",
"postal_code": "<string>",
"address_line2": "<string>"
}
],
"currency": "INR",
"total_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"order": {
"status": "pending",
"type": "<string>",
"catalog_id": "<string>",
"items": [
{
"name": "<string>",
"amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"quantity": 123,
"retailer_id": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>",
"voice": true
},
"sale_amount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"country_of_origin": "<string>",
"importer_name": "<string>",
"importer_address": "<string>"
}
],
"subtotal": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"tax": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"shipping": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"discount": {
"offset": 100,
"value": 1234,
"description": "<string>",
"discount_program_name": "<string>"
},
"expiration": {
"timestamp": "1727438564",
"description": "<string>"
},
"description": "<string>"
},
"payment_settings": [
{
"type": "payment_gateway",
"payment_gateway": {
"type": "billdesk",
"configuration_name": "<string>",
"billdesk": {
"additional_info1": "<string>",
"additional_info2": "<string>",
"additional_info3": "<string>",
"additional_info4": "<string>",
"additional_info5": "<string>",
"additional_info6": "<string>",
"additional_info7": "<string>"
},
"payu": {
"udf1": "<string>",
"udf2": "<string>",
"udf3": "<string>",
"udf4": "<string>"
},
"razorpay": {
"receipt": "<string>",
"notes": {}
},
"zaakpay": {
"extra1": "<string>",
"extra2": "<string>"
}
}
}
]
},
"cards": [
{
"card_index": 4,
"type": "cta_url",
"header": {
"type": "image",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>"
},
"video": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>"
}
},
"action": {
"name": "cta_url",
"parameters": {
"display_text": "See Docs",
"url": "https://developers.facebook.com/docs/whatsapp"
},
"buttons": [
{
"type": "quick_reply",
"quick_reply": {
"title": "<string>",
"id": "<string>"
}
}
]
},
"body": {
"text": "<string>"
}
}
]
},
"body": {
"text": "<string>"
},
"header": {
"type": "text",
"text": "<string>",
"image": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>"
},
"video": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>"
},
"document": {
"id": "<string>",
"link": "<string>",
"caption": "<string>",
"filename": "<string>"
}
},
"footer": {
"text": "<string>"
}
},
"contacts": [
{
"name": {
"formatted_name": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"middle_name": "<string>",
"suffix": "<string>",
"prefix": "<string>"
},
"addresses": [
{
"street": "<string>",
"city": "<string>",
"state": "<string>",
"zip": "<string>",
"country": "<string>",
"country_code": "<string>",
"type": "WORK"
}
],
"birthday": "2022-09-27",
"emails": [
{
"email": "<string>",
"type": "WORK"
}
],
"org": {
"company": "<string>",
"department": "<string>",
"title": "<string>"
},
"phones": [
{
"phone": "<string>",
"type": "<string>",
"wa_id": "<string>"
}
],
"urls": [
{
"url": "<string>",
"type": "<string>"
}
],
"vcard": "<string>",
"origin": "contact_request"
}
],
"reaction": {
"message_id": "wamid.BgNODYxN...",
"emoji": "<string>"
},
"context": {
"message_id": "wamid.BgNODYxN..."
},
"externalId": "<string>",
"category": "utility",
"ttlSeconds": 600,
"status": "accepted",
"errorCode": "INTERNAL_SERVER_ERROR",
"errorMessage": "<string>",
"createTime": "2022-06-01T12:00:00.000Z",
"updateTime": "2022-06-01T12:00:00.000Z",
"sendTime": "2022-06-01T12:00:00.000Z",
"deliverTime": "2022-06-01T12:00:00.000Z",
"readTime": "2022-06-01T12:00:00.000Z",
"totalPrice": 0.05,
"currency": "USD",
"regionCode": "US",
"pricingCategory": "referral_conversion",
"pricingModel": "PMP",
"pricingType": "regular",
"whatsappApiError": {
"message": "HSM Template creation failed",
"code": 200002,
"type": "OAuthException",
"is_transient": false,
"error_subcode": 2388109,
"error_user_msg": "This message template cannot be created.",
"error_user_title": "Message Cannot Be Submitted",
"fbtrace_id": "AVGjJ7ia2zJkrHG",
"error_data": "<string>"
},
"bizType": "whatsapp",
"verificationId": "VERIFICATION-ID"
}{
"error": {
"status": 404,
"code": "NOT_FOUND",
"message": "The requested resource does not exist.",
"target": "",
"docUrl": "",
"requestId": "req_1KjtKI80IKoaJNa6n6p",
"whatsappApiError": {
"message": "HSM Template creation failed",
"code": 200002,
"type": "OAuthException",
"is_transient": false,
"error_subcode": 2388109,
"error_user_msg": "This message template cannot be created.",
"error_user_title": "Message Cannot Be Submitted",
"fbtrace_id": "AVGjJ7ia2zJkrHG",
"error_data": "<string>"
},
"metaBusinessAgentApiError": {
"title": "<string>",
"detail": "<string>",
"type": "<string>",
"status": 123,
"requestId": "<string>"
}
}
}{
"error": {
"status": 404,
"code": "NOT_FOUND",
"message": "The requested resource does not exist.",
"target": "",
"docUrl": "",
"requestId": "req_1KjtKI80IKoaJNa6n6p",
"whatsappApiError": {
"message": "HSM Template creation failed",
"code": 200002,
"type": "OAuthException",
"is_transient": false,
"error_subcode": 2388109,
"error_user_msg": "This message template cannot be created.",
"error_user_title": "Message Cannot Be Submitted",
"fbtrace_id": "AVGjJ7ia2zJkrHG",
"error_data": "<string>"
},
"metaBusinessAgentApiError": {
"title": "<string>",
"detail": "<string>",
"type": "<string>",
"status": 123,
"requestId": "<string>"
}
}
}{
"error": {
"status": 404,
"code": "NOT_FOUND",
"message": "The requested resource does not exist.",
"target": "",
"docUrl": "",
"requestId": "req_1KjtKI80IKoaJNa6n6p",
"whatsappApiError": {
"message": "HSM Template creation failed",
"code": 200002,
"type": "OAuthException",
"is_transient": false,
"error_subcode": 2388109,
"error_user_msg": "This message template cannot be created.",
"error_user_title": "Message Cannot Be Submitted",
"fbtrace_id": "AVGjJ7ia2zJkrHG",
"error_data": "<string>"
},
"metaBusinessAgentApiError": {
"title": "<string>",
"detail": "<string>",
"type": "<string>",
"status": 123,
"requestId": "<string>"
}
}
}Authorizations
Body
application/json
- Template message
- Text message
- Image message
- Video message
- Audio message
- Document message
- Sticker message
- Location message
- Interactive message
- Contacts message
- Reaction message
Set type, then choose the matching message schema branch below. Each branch shows the common fields plus the matching content field required for that message type. At least one of to or recipient is required. If both are provided, to takes precedence and recipient is ignored.
Must be template for this request body variant.
Available options:
template Example:
"template"
The WhatsApp template message object containing the template name, language, and optional component parameters for variable substitution in the template.
Show child attributes
Show child attributes
The recipient's WhatsApp Business-scoped user ID (BSUID) or parent BSUID. Required when to is not provided.
Example:
"US.1234"
The recipient's profile information. Used to persist WhatsApp username in username-only or BSUID send scenarios.
Show child attributes
Show child attributes
Used to mention a specific message you are replying to. The reply can be any message type.
Show child attributes
Show child attributes
A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.
Optional.
Indicates the category of the message to be sent with Direct Send. Supported values are utility and authentication.
Use utility for business-initiated utility messages. Messages sent with utility are charged at utility rates.
Use authentication for business-initiated authentication messages. Messages sent with authentication are charged at authentication rates. Authentication Direct Send only supports text messages.
Available options:
utility, authentication Example:
"utility"
Optional.
Message time-to-live in seconds for Direct Send utility or authentication messages.
The supported range is 30 seconds to 43200 seconds (12 hours). An explicit value overrides the template TTL. If omitted, YCloud inherits a positive template TTL up to 43200 seconds; otherwise, Meta uses its default TTL. An inherited value below 30 seconds fails validation.
Required range:
30 <= x <= 43200Example:
600
Optional.
Whether to send the message through Direct Send. Defaults to false.
Set this to true to send the message through Direct Send. Utility Direct Send is in public beta; no allowlist or access application is required. See Utility Direct Send.
For template messages, the template must be convertible to a Direct Send message type. Supported Direct Send message types for template conversion are:
- Text messages
- Interactive Call-to-Action URL button messages
- Interactive reply button messages
Optional.
Business-defined template name for a Utility Direct Send message submitted through synchronous POST /v2/whatsapp/messages/sendDirectly or asynchronous POST /v2/whatsapp/messages.
The value is case-sensitive and may contain only lowercase letters, digits, and underscores. It does not enable Direct Send by itself. When Direct Send is not selected, this field is ignored.
The name must not already be used by a non-Direct-Send template in the sender WABA. A conflict is rejected before the synchronous provider call or asynchronous acceptance, so an asynchronous conflict does not return a message ID. This field is not supported for Authentication Direct Send.
Example:
"order_update_ds"
Optional.
If set to true, the message will not be sent to users who have unsubscribed from your account. Defaults to false.
Only use for POST /v2/whatsapp/messages. If the user has unsubscribed, we will push webhook notifications with whatsappMessage.errorCode set to RECIPIENT_UNSUBSCRIBED.
Not applicable to POST /v2/whatsapp/messages/sendDirectly.
Optional.
If set to true, the message will not be sent to users in your block list. Defaults to false.
Only use for POST /v2/whatsapp/messages. If the user is in your block list, we will push webhook notifications with whatsappMessage.errorCode set to RECIPIENT_IN_BLOCK_LIST.
Not applicable to POST /v2/whatsapp/messages/sendDirectly.
Response
The request is successfully accepted.
WhatsApp outbound message object.
Unique ID of the message.
WhatsApp Business Account ID.
Example:
"whatsapp-business-account-id"
The original message ID on WhatsApp's platform.
Example:
"wamid.BgNODYxN..."
The recipient value submitted in the request when a BSUID or parent BSUID was used.
Example:
"US.1234"
The recipient's WhatsApp Business-scoped user ID (BSUID).
Example:
"US.1234"
Alias of recipientUserId kept for compatibility.
Example:
"US.1234"
The recipient's parent WhatsApp Business-scoped user ID.
Example:
"US.ENT.1234"
Alias of parentRecipientUserId kept for compatibility.
Example:
"US.ENT.1234"
The recipient's profile information, including WhatsApp username when available.
Show child attributes
Show child attributes
WhatsApp defines a conversation as a 24-hour session of messaging between a person and a business.
This field is present after the message status changes to sent.
See also Conversation-Based Pricing.
Show child attributes
Show child attributes
WhatsApp outbound message type. See also WhatsApp messages.
Available options:
template, text, image, audio, video, document, sticker, location, interactive, contacts, reaction Use for sending a WhatsApp template message.
Show child attributes
Show child attributes
WhatsApp Message Text Object.
Show child attributes
Show child attributes
Use for image, gif, video, audio, document, or sticker messages.
See also Supported Media Types.
Note: Either id or link must be provided, but not both. These parameters are mutually exclusive.
Reference: WhatsApp Cloud API Media Object
Show child attributes
Show child attributes
Use for image, gif, video, audio, document, or sticker messages.
See also Supported Media Types.
Note: Either id or link must be provided, but not both. These parameters are mutually exclusive.
Reference: WhatsApp Cloud API Media Object
Show child attributes
Show child attributes
Use for image, gif, video, audio, document, or sticker messages.
See also Supported Media Types.
Note: Either id or link must be provided, but not both. These parameters are mutually exclusive.
Reference: WhatsApp Cloud API Media Object
Show child attributes
Show child attributes
Use for image, gif, video, audio, document, or sticker messages.
See also Supported Media Types.
Note: Either id or link must be provided, but not both. These parameters are mutually exclusive.
Reference: WhatsApp Cloud API Media Object
Show child attributes
Show child attributes
Use for image, gif, video, audio, document, or sticker messages.
See also Supported Media Types.
Note: Either id or link must be provided, but not both. These parameters are mutually exclusive.
Reference: WhatsApp Cloud API Media Object
Show child attributes
Show child attributes
Use for location messages.
Show child attributes
Show child attributes
Use for interactive messages.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
When a user reacts to messages with an emoji, the message type is set to reaction, and this field is included.
Show child attributes
Show child attributes
Used to mention a specific message you are replying to. The reply can be any message type.
Show child attributes
Show child attributes
A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.
The Direct Send category, such as utility or authentication, when applicable.
Example:
"utility"
The configured Direct Send message lifetime in seconds, when applicable.
Example:
600
WhatsApp message status. One of accepted, failed, sent, delivered, read.
accepted: The messaging request is accepted by our system.failed: A message sent by your business failed to send.sent: A message sent by your business is in transit within WhatsApp's systems.delivered: A message sent by your business was delivered to the user's device.read: A message sent by your business was read by the user.
Available options:
accepted, failed, sent, delivered, read Error code when the message status is failed.
Example:
"INTERNAL_SERVER_ERROR"
Error message when the message status is failed.
Total price of this message.
Note: It's only an estimated price when the status is accepted or sent. It becomes the final price after the message is delivered, i.e., the status is delivered or read.
Example:
0.05
Price currency. ISO 4217 currency code.
Example:
"USD"
The region code of the recipient phone number.
Example:
"US"
The pricing category of the message.
Note: It's only an estimated pricing category when the status is accepted or sent. It becomes final after the message is delivered, i.e., the status is delivered or read.
Available options:
referral_conversion, authentication, authentication_international, marketing, marketing_lite, utility, service The pricing model of the message.
PMP: Per-message pricing applies.CBP: Conversation-based pricing applies.
Available options:
PMP, CBP The pricing type of the message. This field is only available in PMP (Per-Message Pricing) mode.
regular: Indicates the message is billable.free_customer_service: Indicates the message is free because it was either a utility template message or non-template message sent within a customer service window.free_entry_point: Indicates the message is free because it is part of a free-entry point conversation.
Available options:
regular, free_customer_service, free_entry_point The original error object returned by WhatsApp. See Handling Errors, Cloud API Error Codes.
Show child attributes
Show child attributes
This can be either empty or one of whatsapp, or verify. Defaults to whatsapp.
whatsapp: Indicates that the message is sent via the WhatsApp product.verify: Indicates that the message is sent via the Verify product.
Example:
"whatsapp"
The verification ID. Included only when bizType is verify.
Example:
"VERIFICATION-ID"