> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Test webhooks > Send sample webhook payloads and inspect the event schema. Use this reference to inspect the webhook payloads that YCloud sends to your application. Select a named example in the request builder to view its fields. The reference uses `https://example.com` as a reserved placeholder. For your own tests, replace it with your application's webhook URL in the generated request. Your application hosts this endpoint; YCloud does not host `/webhooks/ycloud`. Sending a sample payload tests your receiver. It does not trigger a webhook delivery from YCloud. The example `YCloud-Signature` is a sample value; it is not a valid signature for an edited payload or your endpoint's secret. Validate the `YCloud-Signature` header before processing an event. See [Configure webhooks](/en/api-reference/guides/api-fundamentals/configure-webhooks) for setup and delivery guidance. ## Receiver response Return any `2xx` status after you have authenticated and durably accepted the event. Process slow work asynchronously so YCloud does not retry a delivery that your application already received. ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} HTTP/1.1 200 OK ``` Create an endpoint, validate signatures, and handle retries. Understand event triggers and scenario-specific handling. ## OpenAPI ````yaml openapi/webhooks/testing-webhooks.yaml POST /webhooks/ycloud openapi: 3.0.0 info: description: Shows the detailed structured webhook payload object. version: v2 title: Webhooks termsOfService: https://ycloud.com/terms-service contact: email: service@ycloud.com servers: - url: https://example.com description: Reserved placeholder for your webhook receiver security: [] tags: - name: Webhook Payload Object externalDocs: description: Homepage url: https://ycloud.com paths: /webhooks/ycloud: post: tags: - Webhook Payload Object summary: Test webhooks description: >- Shows a request sent to your webhook receiver. The reserved example.com URL does not trigger a real YCloud webhook delivery. operationId: test-webhooks parameters: - name: YCloud-Signature in: header required: false schema: type: string example: >- t=1654084800,s=8eb70f2acb056c2119acbee8fdd98a889021d9c268bc9ad248a4182c40e31119 requestBody: content: application/json: schema: $ref: '#/components/schemas/Event' examples: echo_text: summary: Outbound text echo description: >- Store the text from whatsappMessage.text.body. id and wamid link subsequent status events. value: id: evt_example_echo_text type: whatsapp.echo_message.created apiVersion: v2 createTime: '2026-09-09T02:00:00.000Z' whatsappMessage: id: MESSAGE_ID wamid: wamid.EXAMPLE wabaId: WABA_ID from: '+12025550123' to: '+12025550124' recipientUserId: GB.898232076600896 type: text text: body: Hello! How can I help you? status: sent createTime: '2026-09-09T02:00:00.000Z' sendTime: '2026-09-09T02:00:00.000Z' echo_image: summary: Outbound image echo description: >- Message content varies by type. Treat media IDs as provider references, not public download URLs. value: id: evt_example_echo_image type: whatsapp.echo_message.created apiVersion: v2 createTime: '2026-09-09T02:00:00.000Z' whatsappMessage: id: IMAGE_MESSAGE_ID wamid: wamid.IMAGE_EXAMPLE wabaId: WABA_ID from: '+12025550123' to: '+12025550124' recipientUserId: GB.898232076600896 type: image image: id: MEDIA_ID mime_type: image/jpeg status: sent createTime: '2026-09-09T02:00:00.000Z' sendTime: '2026-09-09T02:00:00.000Z' echo_delivered: summary: Echo message delivered description: >- Correlate with the created event by id or wamid. Updated events omit message content and type. value: id: evt_example_echo_delivered type: whatsapp.echo_message.updated apiVersion: v2 createTime: '2026-09-09T02:00:03.000Z' whatsappMessage: id: MESSAGE_ID wamid: wamid.EXAMPLE wabaId: WABA_ID from: '+12025550123' to: '+12025550124' recipientUserId: GB.898232076600896 status: delivered updateTime: '2026-09-09T02:00:01.000Z' deliverTime: '2026-09-09T02:00:01.000Z' echo_read: summary: Echo message read description: >- Correlate with the created event by id or wamid. Updated events omit message content and type. value: id: evt_example_echo_read type: whatsapp.echo_message.updated apiVersion: v2 createTime: '2026-09-09T02:00:03.000Z' whatsappMessage: id: MESSAGE_ID wamid: wamid.EXAMPLE wabaId: WABA_ID from: '+12025550123' to: '+12025550124' recipientUserId: GB.898232076600896 status: read updateTime: '2026-09-09T02:00:02.000Z' readTime: '2026-09-09T02:00:02.000Z' echo_sent: summary: Late sent status after read description: >- A lower-ranked source status can arrive after read. Record the event without downgrading your current message status. value: id: evt_example_echo_sent type: whatsapp.echo_message.updated apiVersion: v2 createTime: '2026-09-09T02:00:03.000Z' whatsappMessage: id: MESSAGE_ID wamid: wamid.EXAMPLE wabaId: WABA_ID from: '+12025550123' to: '+12025550124' recipientUserId: GB.898232076600896 status: sent updateTime: '2026-09-09T02:00:00.000Z' sendTime: '2026-09-09T02:00:00.000Z' echo_failed: summary: Failed echo message description: >- This is a separate failed message, not a transition from read. Failed updates include source error details when available. value: id: evt_example_echo_failed type: whatsapp.echo_message.updated apiVersion: v2 createTime: '2026-09-09T02:00:03.000Z' whatsappMessage: id: FAILED_MESSAGE_ID wamid: wamid.FAILED_EXAMPLE wabaId: WABA_ID from: '+12025550123' to: '+12025550124' recipientUserId: GB.898232076600896 status: failed errorCode: '131000' errorMessage: Provider failure updateTime: '2026-09-09T02:00:03.000Z' agent_handover: summary: Agent hands control to your application description: >- APP_CONTROL_TAKEN reports control transfer, not an Inbox employee assignment or custom handoff message delivery. actor is the previous owner app ID in this example. value: id: evt_example_agent_handover type: whatsapp.meta_business_agent.handover.updated apiVersion: v2 createTime: '2026-09-09T02:00:04.000Z' whatsappMetaBusinessAgent: agentId: 00000000-0000-4000-8000-000000000001 metaAgentId: META_AGENT_ID phoneNumberId: PHONE_NUMBER_ID wabaId: WABA_ID consumerPhoneNumber: '+12025550124' controlState: APP_CONTROL_TAKEN actor: PREVIOUS_OWNER_APP_ID reason: customer_request timestamp: 1788919204000 contact_attributes_changed: summary: Contact attributes changed event description: Example payload when contact attributes are changed value: id: evt_1234567890 type: contact.attributes_changed apiVersion: v2 createTime: '2024-01-01T12:00:00.000Z' contactAttributesChanged: id: '1824266594102064128' updateTime: '2024-01-01T12:00:00.000Z' changedAttributes: remark_name: oldValue: Standard customer newValue: Priority customer email: oldValue: john.doe@example.com newValue: johnny.doe@example.com tags: oldValue: - premium - newsletter newValue: - premium - newsletter - vip extra: - action: ADDED id: 686dd294334be8606a5bf312 value: vip contact_created: summary: Contact created event description: Example payload when a new contact is created value: id: evt_2345678901 type: contact.created apiVersion: v2 createTime: '2024-01-01T12:00:00.000Z' contactCreated: id: '1824266594102064128' remarkName: Priority customer nickName: John Doe realName: John Smith phoneNumber: '+16315551111' countryCode: US countryName: United States email: john.doe@example.com sourceType: api sourceId: import_batch_123 sourceUrl: https://example.com/signup lastSeen: '2024-01-01T11:59:00.000Z' lastConnectedNumber: '+16315552222' ownerEmail: owner@example.com tags: - premium - newsletter createTime: '2024-01-01T12:00:00.000Z' updateTime: '2024-01-01T12:00:00.000Z' blocked: false customAttributes: attr1: value1 attr2: value2 attr3: 123 contact_deleted: summary: Contact deleted event description: Example payload when a contact is deleted value: id: evt_3456789012 type: contact.deleted apiVersion: v2 createTime: '2024-01-01T12:00:00.000Z' contactDeleted: id: '1824266594102064128' remarkName: Former customer nickName: John Doe phoneNumber: '+16315551111' updateTime: '2024-01-01T12:00:00.000Z' contact_note_created: summary: Contact note created event value: id: evt_1234567890abcdef12345678 type: contact.note.created apiVersion: v2 createTime: '2024-01-01T12:00:00.000Z' contactNote: id: 6a3de646e18f344f743aaa4d contactId: '1824266594102064128' username: alice_01 phoneNumber: '+16315551111' content: Customer prefers follow-up in the morning. createTime: '2024-01-01T12:00:00.000Z' updateTime: '2024-01-01T12:00:00.000Z' contact_note_updated: summary: Contact note updated event value: id: evt_2234567890abcdef12345678 type: contact.note.updated apiVersion: v2 createTime: '2024-01-02T12:00:00.000Z' contactNote: id: 6a3de646e18f344f743aaa4d contactId: '1824266594102064128' username: alice_01 phoneNumber: '+16315551111' content: Customer now prefers afternoon follow-up. createTime: '2024-01-01T12:00:00.000Z' updateTime: '2024-01-02T12:00:00.000Z' contact_note_deleted: summary: Contact note deleted event description: >- Emitted only for an independent note deletion, not for contact deletion cascade. value: id: evt_3234567890abcdef12345678 type: contact.note.deleted apiVersion: v2 createTime: '2024-01-03T12:00:00.000Z' contactNote: id: 6a3de646e18f344f743aaa4d contactId: '1824266594102064128' username: alice_01 phoneNumber: '+16315551111' content: Customer now prefers afternoon follow-up. createTime: '2024-01-01T12:00:00.000Z' updateTime: '2024-01-02T12:00:00.000Z' contact_unsubscribe_created: summary: Customer cancels subscription event description: Example payload when a customer cancels subscription value: id: evt_3456789012 type: contact.unsubscribe.created apiVersion: v2 createTime: '2024-01-01T12:00:00.000Z' unsubscriberChanged: phoneNumber: '+16315551111' source: Whatsapp updateTime: '2024-01-01T12:00:00.000Z' contact_unsubscribe_deleted: summary: Customer resumes subscription description: Example payload when a customer resumes subscription value: id: evt_3456789012 type: contact.unsubscribe.deleted apiVersion: v2 createTime: '2024-01-01T12:00:00.000Z' unsubscriberChanged: phoneNumber: '+16315551111' source: Whatsapp updateTime: '2024-01-01T12:00:00.000Z' whatsapp_phone_number_business_username_updated: summary: WhatsApp phone number Business Username updated event description: >- Example payload when a WhatsApp phone number Business Username becomes active value: id: evt_business_username_updated_123 type: whatsapp.phone_number.business_username_updated apiVersion: v2 createTime: '2026-05-26T12:00:00.000Z' whatsappPhoneNumber: id: '1234567890123456' phoneNumber: '+16315551111' displayPhoneNumber: +1 631-555-1111 wabaId: whatsapp-business-account-id businessUsername: acme.support businessUsernameStatus: active businessUsernameUpdatedAt: '2026-05-26T12:00:00.000Z' whatsapp_phone_number_business_username_reserved: summary: WhatsApp phone number Business Username reserved event description: >- Example payload when a WhatsApp phone number has a reserved Business Username request value: id: evt_business_username_pending_123 type: whatsapp.phone_number.business_username_updated apiVersion: v2 createTime: '2026-05-26T12:30:00.000Z' whatsappPhoneNumber: id: '1234567890123456' phoneNumber: '+16315551111' displayPhoneNumber: +1 631-555-1111 wabaId: whatsapp-business-account-id businessUsername: acme.support businessUsernameStatus: reserved requestedBusinessUsername: acme.help businessUsernameUpdatedAt: '2026-05-26T12:30:00.000Z' whatsapp_template_correct_category_detection: summary: Utility Direct Send category detection event description: >- Meta detected marketing content in a Utility Direct Send message. Subscribe to this event through the webhook endpoint API. value: id: evt_direct_send_category_123 type: whatsapp.template.correct_category_detection apiVersion: v2 createTime: '2026-09-17T08:00:00.000Z' whatsappTemplate: officialTemplateId: official-template-id wabaId: whatsapp-business-account-id name: auto_generated_sample language: en_US category: MARKETING previousCategory: UTILITY whatsapp_direct_send_restricted: summary: Utility Direct Send restriction event description: >- Meta restricted Utility Direct Send for 7 days after repeated category misuse. value: id: evt_direct_send_restriction_123 type: whatsapp.business_account.updated apiVersion: v2 createTime: '2026-09-17T08:00:00.000Z' whatsappBusinessAccount: id: whatsapp-business-account-id name: Example business updateEvent: ACCOUNT_RESTRICTION violationType: DIRECT_SEND_UTILITY_CATEGORY_ABUSE_STRIKE_1 restrictions: - restrictionType: RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES expiration: '2026-09-24T08:00:00.000Z' whatsapp_template_archived: summary: WhatsApp template archived event description: Example payload when a WhatsApp template is archived value: id: evt_template_archived_123 type: whatsapp.template.reviewed apiVersion: v2 createTime: '2024-01-01T12:00:00.000Z' whatsappTemplate: id: template-id officialTemplateId: official-template-id wabaId: whatsapp-business-account-id name: sample_whatsapp_template language: en category: MARKETING status: ARCHIVED statusUpdateEvent: ARCHIVED createTime: '2024-01-01T12:00:00.000Z' updateTime: '2024-01-01T12:00:00.000Z' whatsapp_template_unarchived: summary: WhatsApp template unarchived event description: >- Example payload when a WhatsApp template is unarchived. The template status is the current status returned by Meta and does not represent a new approval review. value: id: evt_template_unarchived_123 type: whatsapp.template.reviewed apiVersion: v2 createTime: '2024-01-01T12:00:00.000Z' whatsappTemplate: id: template-id officialTemplateId: official-template-id wabaId: whatsapp-business-account-id name: sample_whatsapp_template language: en category: MARKETING status: APPROVED statusUpdateEvent: UNARCHIVED createTime: '2024-01-01T12:00:00.000Z' updateTime: '2024-01-01T12:00:00.000Z' whatsapp_call_connect: summary: WhatsApp call connect event description: Example payload when a WhatsApp call is connected value: id: evt_call_connect_123 type: whatsapp.call.connect apiVersion: v2 createTime: '2024-01-01T12:00:00.000Z' callingConnect: id: 6757b723960b25543b9ecc66 wacid: wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIEF phoneId: '461269257068832' from: '+6281361905133' to: '+6283138205150' direction: USER_INITIATED dialTime: 1733826430000 sdpType: offer sdp: "v=0\r\no=- 1732169627243 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE audio\r\na=msid-semantic: WMS af3b01e3-eb42-4244-812e-db903c062ae7\r\na=ice-lite\r\nm=audio 3480 UDP/TLS/RTP/SAVPF 111 126\r\nc=IN IP4 31.13.87.130\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:785588535 1 udp 2122260223 31.13.87.130 3480 typ host generation 0 network-cost 50\r\na=candidate:1906600321 1 udp 2122262783 2a03:2880:f217:d0:face:b00c:0:699c 3480 typ host generation 0 network-cost 50\r\na=ice-ufrag:CvRXRnInnWhQzLIE\r\na=ice-pwd:HGXUGAFI8wK6seuVknBT2Q==\r\na=fingerprint:sha-256 FB:56:A1:C5:37:35:6C:5C:1B:05:23:B0:DD:BB:2E:C9:5F:E4:70:61:7B:D9:1D:09:84:76:46:23:12:38:B7:01\r\na=setup:actpass\r\na=mid:audio\r\na=sendrecv\r\na=msid:af3b01e3-eb42-4244-812e-db903c062ae7 WhatsAppTrack1\r\na=rtcp-mux\r\na=rtpmap:111 opus/48000/2\r\na=rtcp-fb:111 transport-cc\r\na=fmtp:111 maxaveragebitrate=20000;maxplaybackrate=16000;minptime=20;sprop-maxcapturerate=16000;useinbandfec=1\r\na=rtpmap:126 telephone-event/8000\r\na=maxptime:20\r\na=ptime:20\r\na=ssrc:659928310 cname:WhatsAppAudioStream1\r\n" whatsapp_call_terminate: summary: WhatsApp call terminate event description: Example payload when a WhatsApp call is terminated value: id: evt_6757b889a5a42d369ef48481 type: whatsapp.call.terminate apiVersion: v2 createTime: '2024-12-10T03:42:01.822Z' callingTerminate: id: 6757b889960b25543b9ecc67 wacid: wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIEFENjB phoneId: '461269257068832' from: '+6281361905133' to: '+6283138205150' direction: USER_INITIATED startTime: 1733734738000 endTime: 1733734771000 duration: 33 status: COMPLETED whatsapp_call_status_updated: summary: WhatsApp call status updated event description: Example payload when a WhatsApp call status is updated value: id: evt_676e5ab57a9cb742d02d7646 type: whatsapp.call.status.updated apiVersion: v2 createTime: '2024-12-27T07:41:28.422Z' callingStatusUpdated: wabaId: '188234691048809' wacid: wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE phoneId: '461269257068832' status: RINGING recipientPhone: '+6281361905133' whatsapp_call_recording_updated: summary: WhatsApp call recording updated event description: >- Example payload when an API-sourced call recording becomes available value: id: evt_call_recording_01JZ8K4V7H3P6Q9R2T5W8X1Y4Z type: whatsapp.call.recording.updated apiVersion: v2 createTime: '2026-08-04T08:00:00.000Z' callingRecording: wacid: wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE phoneId: '461269257068832' mediaAssetId: 66b1f0c2e4b05c2d8f1a3b47 status: AVAILABLE whatsapp_call_transcription_updated: summary: WhatsApp call transcription updated event description: >- Example payload when an API-sourced call transcription permanently fails value: id: evt_call_transcription_01JZ8K5A9C4D7E0F3G6H9J2K5M type: whatsapp.call.transcription.updated apiVersion: v2 createTime: '2026-08-04T08:01:00.000Z' callingTranscription: wacid: wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE phoneId: '461269257068832' mediaAssetId: 66b1f0d9e4b05c2d8f1a3b48 status: FAILED error: code: CALLING_TRANSCRIPTION_PROCESSING_FAILED retryable: false whatsapp_group_lifecycle_update: summary: WhatsApp group lifecycle update event description: Example payload when a WhatsApp group is created value: id: evt_group_lifecycle_123 type: whatsapp.group.lifecycle_update apiVersion: v2 createTime: '2026-05-13T00:00:00.000Z' whatsappGroup: wabaId: '123456789012345' displayPhoneNumber: '16315551111' phoneNumberId: '1234567890123456' field: group_lifecycle_update type: group_create requestId: REQ_1 status: created groupId: 120363345678901234@g.us inviteLink: https://chat.whatsapp.com/AbCdEfGhIjK subject: New Purchase Inquiry description: Group for purchase inquiries. joinApprovalMode: auto_approve webhookTime: '2026-05-13T00:00:00.000Z' dedupeKey: >- 123456789012345|REQ_1|group_lifecycle_update|group_create|created whatsapp_group_participants_update: summary: WhatsApp group participants update event description: Example payload when WhatsApp group participants are added value: id: evt_group_participants_123 type: whatsapp.group.participants_update apiVersion: v2 createTime: '2026-05-13T00:00:00.000Z' whatsappGroup: wabaId: '123456789012345' field: group_participants_update type: group_participants_add status: added groupId: 120363345678901234@g.us waId: '16315551111' recipientUserId: US.1234 parentRecipientUserId: US.parent123 customerProfile: name: John Doe username: john_doe addedParticipants: - input: US.1234 waId: '16315551111' recipientUserId: US.1234 parentRecipientUserId: US.parent123 customerProfile: name: John Doe username: john_doe webhookTime: '2026-05-13T00:00:00.000Z' whatsapp_group_settings_update: summary: WhatsApp group settings update event description: Example payload when WhatsApp group settings are updated value: id: evt_group_settings_123 type: whatsapp.group.settings_update apiVersion: v2 createTime: '2026-05-13T00:00:00.000Z' whatsappGroup: wabaId: '123456789012345' field: group_settings_update type: group_settings_update requestId: REQ_2 status: updated groupId: 120363345678901234@g.us subject: Updated Purchase Inquiry description: Updated group description. settings: - name: group_subject text: Updated Purchase Inquiry updateSuccessful: true - name: group_description text: Updated group description. updateSuccessful: true webhookTime: '2026-05-13T00:00:00.000Z' whatsapp_group_status_update: summary: WhatsApp group status update event description: >- Example payload when a WhatsApp group suspension status changes value: id: evt_group_status_123 type: whatsapp.group.status_update apiVersion: v2 createTime: '2026-05-13T00:00:00.000Z' whatsappGroup: wabaId: '123456789012345' field: group_status_update type: group_suspend status: suspended groupId: 120363345678901234@g.us webhookTime: '2026-05-13T00:00:00.000Z' responses: '200': description: The request is successfully accepted. components: schemas: Event: type: object description: >- Represents a webhook event payload. Every event contains certain common properties: `id`, `type`, `apiVersion`, `createTime`. Each event may also contain some properties unique to the event. For example, `sms` is returned when `type` is `sms.message.updated`. required: - id - type - apiVersion - createTime properties: id: type: string description: Unique ID for the event. minLength: 6 maxLength: 128 type: $ref: '#/components/schemas/EventType' apiVersion: type: string description: The API version used to render this event. example: v2 createTime: type: string format: date-time description: >- The time at which this event was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' phase: type: integer format: int32 description: >- Included when `type` is `whatsapp.smb.history` and the event was generated from a Meta history chunk. Identifies the chunk's synchronization phase. example: 1 progress: type: integer format: int32 description: >- Included when `type` is `whatsapp.smb.history` and the event was generated from a Meta history chunk. Reports the chunk's synchronization progress. example: 73 contactAttributesChanged: $ref: '#/components/schemas/ContactAttributesChanged' description: Included when `type` is `contact.attributes_changed`. contactCreated: $ref: '#/components/schemas/ContactCreated' description: Included when `type` is `contact.created`. contactDeleted: $ref: '#/components/schemas/ContactDeleted' description: Included when `type` is `contact.deleted`. contactNote: $ref: '#/components/schemas/ContactNote' description: >- Included when `type` is `contact.note.created`, `contact.note.updated`, or `contact.note.deleted`. contactUnsubscribeCreated: $ref: '#/components/schemas/ContactUnsubscribeCreated' description: Included when `type` is `contact.unsubscribe.created`. contactUnsubscribeDeleted: $ref: '#/components/schemas/ContactUnsubscribeDeleted' description: Included when `type` is `contact.unsubscribe.deleted`. emailDelivery: $ref: '#/components/schemas/EmailDelivery' description: Included when `type` is `email.delivery.updated`. sms: $ref: '#/components/schemas/Sms' description: Included when `type` is `sms.message.updated`. smsInbound: $ref: '#/components/schemas/SmsInbound' description: Included when `type` is `sms.inbound.received`. voice: $ref: '#/components/schemas/Voice' description: Included when `type` is `voice.message.updated`. whatsappBusinessAccount: $ref: '#/components/schemas/WhatsappBusinessAccount' description: >- Included when `type` is `whatsapp.business_account.deleted`, `whatsapp.business_account.reviewed`, or `whatsapp.business_account.updated`. whatsappInboundMessage: description: >- Included when `type` is `whatsapp.inbound_message.received`, or when `type` is `whatsapp.smb.history` for an inbound history message. It is omitted for a metadata-only history chunk. allOf: - $ref: '#/components/schemas/WhatsappInboundMessage' whatsappMessage: description: >- Included when `type` is `whatsapp.message.updated`, `whatsapp.smb.message.created`, or when `type` is `whatsapp.smb.history` for an outbound history message. Also included for `whatsapp.echo_message.created` and `whatsapp.echo_message.updated`, where the Agent echo subset applies. It is omitted for a metadata-only history chunk. type: object whatsappMetaBusinessAgent: $ref: '#/components/schemas/MetaBusinessAgentWebhook' description: >- Included for whatsapp.meta_business_agent.handover.updated. Currently limited to Public REST API Agents. whatsappGroup: $ref: '#/components/schemas/WhatsappGroupWebhook' description: >- Included when `type` is `whatsapp.group.lifecycle_update`, `whatsapp.group.participants_update`, `whatsapp.group.settings_update`, `whatsapp.group.status_update`, or when `type` is `whatsapp.message.updated` for group message status updates. whatsappPhoneNumber: $ref: '#/components/schemas/WhatsappPhoneNumber' description: >- Included when `type` is `whatsapp.phone_number.deleted`, `whatsapp.phone_number.name_updated`, `whatsapp.phone_number.quality_updated`, or `whatsapp.phone_number.business_username_updated`. whatsappPayment: $ref: '#/components/schemas/WhatsappPayment' description: Included when `type` is `whatsapp.payment.updated`. whatsappTemplate: $ref: '#/components/schemas/WhatsappTemplate' description: >- Included when `type` is `whatsapp.template.reviewed`, `whatsapp.template.quality_updated`, `whatsapp.template.category_updated`, or `whatsapp.template.correct_category_detection`. callingConnect: $ref: '#/components/schemas/CallingConnect' description: Included when `type` is `whatsapp.call.connect`. callingTerminate: $ref: '#/components/schemas/CallingTerminate' description: Included when `type` is `whatsapp.call.terminate`. callingStatusUpdated: $ref: '#/components/schemas/CallingStatusUpdated' description: Included when `type` is `whatsapp.call.status.updated`. callingRecording: $ref: '#/components/schemas/CallingMediaUpdated' description: Included when `type` is `whatsapp.call.recording.updated`. callingTranscription: $ref: '#/components/schemas/CallingMediaUpdated' description: Included when `type` is `whatsapp.call.transcription.updated`. flowChanges: $ref: '#/components/schemas/WhatsappFlowStatusChange' description: Included when `type` is `whatsapp.flow.status_change`. whatsappUserPreference: $ref: '#/components/schemas/WhatsappUserPreference' description: Included when `type` is `whatsapp.user.preferences`. oneOf: - properties: type: enum: - whatsapp.echo_message.created - whatsapp.echo_message.updated whatsappMessage: $ref: '#/components/schemas/WhatsappEchoMessage' required: - whatsappMessage not: required: - whatsappMetaBusinessAgent - properties: type: enum: - whatsapp.meta_business_agent.handover.updated whatsappMetaBusinessAgent: $ref: '#/components/schemas/MetaBusinessAgentWebhook' required: - whatsappMetaBusinessAgent not: required: - whatsappMessage - properties: type: not: enum: - whatsapp.echo_message.created - whatsapp.echo_message.updated - whatsapp.meta_business_agent.handover.updated whatsappMessage: $ref: '#/components/schemas/WhatsappMessage' EventType: type: string description: Type of event. enum: - contact.attributes_changed - contact.created - contact.deleted - contact.unsubscribe.created - contact.unsubscribe.deleted - email.delivery.updated - sms.message.updated - sms.inbound.received - voice.message.updated - whatsapp.business_account.deleted - whatsapp.business_account.reviewed - whatsapp.business_account.updated - whatsapp.inbound_message.received - whatsapp.message.updated - whatsapp.group.lifecycle_update - whatsapp.group.participants_update - whatsapp.group.settings_update - whatsapp.group.status_update - whatsapp.phone_number.deleted - whatsapp.phone_number.name_updated - whatsapp.phone_number.quality_updated - whatsapp.phone_number.business_username_updated - whatsapp.template.category_updated - whatsapp.template.correct_category_detection - whatsapp.template.quality_updated - whatsapp.template.reviewed - whatsapp.call.connect - whatsapp.call.terminate - whatsapp.call.status.updated - whatsapp.call.recording.updated - whatsapp.call.transcription.updated - whatsapp.flow.status_change - whatsapp.payment.updated - whatsapp.user.preferences - contact.note.created - contact.note.updated - contact.note.deleted - whatsapp.echo_message.created - whatsapp.echo_message.updated - whatsapp.meta_business_agent.handover.updated - whatsapp.smb.history - whatsapp.smb.message.created - whatsapp.smb.message.echoes x-enum-descriptions: - Occurs when a contact's attributes are changed. - Occurs when a contact is created. - Occurs when a contact is deleted. - Occurs when a contact unsubscribes from messages. - Occurs when a contact resumes subscription to messages. - >- Occurs when an email delivery status is updated, and the status changes to `delivered` or `failed`. - >- Occurs when an SMS message status is updated, and the status changes to `delivered` or `undelivered`. - >- Occurs when an SMS inbound message is received, which means a user replies to your message. - >- Occurs when a voice message status is updated, and the status changes to `delivered` or `undelivered`. - Occurs when a WhatsApp Business Account is deleted. - Occurs when a WhatsApp Business Account has been reviewed. - >- Occurs when a policy violation happened, WhatsApp Business Account has been banned and more. - Occurs when a WhatsApp inbound message is received. - >- Occurs when a WhatsApp outbound message status is updated, and the status changes to `sent`, `failed`, `delivered`, or `read`. - >- Occurs when a WhatsApp group is created or deleted, including successful and failed results. - Occurs when WhatsApp group participants or join requests are updated. - >- Occurs when WhatsApp group settings are updated, including successful and failed results. - Occurs when a WhatsApp group suspension status is updated. - Occurs when a WhatsApp business phone number is deleted. - >- Occurs when a WhatsApp business phone number's name has been approved or rejected. - >- Occurs when a WhatsApp business phone number's quality-related status is updated, and the status changes to `GREEN`, `YELLOW`, or `RED`. - >- Occurs when a WhatsApp business phone number's Business Username is updated. - Occurs when a WhatsApp template category is updated. - >- Occurs when Meta detects non-utility content in Utility Direct Send. Subscribe through the webhook endpoint API. - Occurs when a WhatsApp template quality rating is updated. - >- Occurs when a WhatsApp template status is updated, and the status changes to `REJECTED`, `APPROVED`, `PAUSED`, `DISABLED`, `IN_APPEAL`, or `ARCHIVED`. - Occurs when a WhatsApp call is connected. - Occurs when a WhatsApp call is terminated. - Occurs when a WhatsApp call status is updated. - >- Occurs when an API-sourced WhatsApp call recording becomes available or permanently fails. - >- Occurs when an API-sourced WhatsApp call transcription becomes available or permanently fails. - Occurs when a WhatsApp flow status is updated. - Occurs when a WhatsApp payment transaction changes. - >- Occurs when a WhatsApp user stops marketing messages or a WhatsApp user resumes marketing messages. - Occurs when a contact note is created. - Occurs when a contact note is updated. - >- Occurs when a contact note is independently deleted. Contact deletion does not emit this event for cascaded notes. - >- Occurs when an outbound echo message is recorded for a Public REST API Agent. - >- Occurs when an outbound echo status is received for a Public REST API Agent; late lower-ranked statuses can also be delivered. - >- Occurs when a supported handover callback transfers control away from a Public REST API Agent. Does not confirm Inbox assignment. - Occurs when WhatsApp Business app sync history message. - Occurs when WhatsApp Business app send message. - Occurs when WhatsApp Business app sends a message echo. ContactAttributesChanged: type: object description: >- Represents a contact attributes changed event. Contains information about which contact attributes were modified and their old/new values. This event is emitted only when at least one persisted contact field actually changes; note-only and contact no-op updates do not emit it. required: - id - updateTime - changedAttributes properties: id: type: string description: The ID of the contact whose attributes were changed. example: '1824266594102064128' updateTime: type: string format: date-time description: >- The time at which the contact attributes were updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2025-07-09T02:24:16.193Z' changedAttributes: type: object description: >- An object containing the changed attributes. Each key represents the name of the changed attribute, and the value contains the old value, new value, and change actions. Keys use the Contact attribute catalog names, including system keys such as `remark_name`, `country_code`, and `meta_username`. additionalProperties: $ref: '#/components/schemas/ContactAttributeChange' example: tags: newValue: - customer - vip extra: - action: ADDED id: 686dd294334be8606a5bf312 value: customer waba_id: oldValue: old_waba_id newValue: new_waba_id extra: - action: CHANGED age: oldValue: 25 newValue: 26 extra: - action: CHANGED is_verified: oldValue: false newValue: true extra: - action: CHANGED ContactCreated: type: object description: |- Represents a contact created event. Contains the full contact information that was created. required: - id properties: id: type: string description: Unique ID for the object. example: '1824266594102064128' remarkName: type: string description: The business-managed remark name for the contact. example: Priority customer nickName: type: string description: Contact's nickname. example: John Doe realName: type: string description: Contact's real name. example: John Smith phoneNumber: type: string description: >- Unique Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' countryCode: type: string description: >- Two-letter country abbreviation. See [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). example: US countryName: type: string description: Full country name. example: United States email: type: string description: |- The contact's email address. If present, the email address must be unique. example: john.doe@example.com sourceType: type: string description: The source type where the contact was created. example: api sourceId: type: string description: The source ID where the contact was created. example: import_batch_123 sourceUrl: type: string description: The source URL where the contact was created. example: https://example.com/signup lastSeen: type: string format: date-time description: >- The time at which the contact last sent a message to your business, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2025-07-09T02:24:16.193Z' lastConnectedNumber: type: string description: The business phone number that the contact last connected to. example: '+16315551111' ownerEmail: type: string description: The email address of the contact's owner. example: support@example.com tags: type: array description: Contact's tags. items: type: string example: - customer - vip createTime: type: string format: date-time description: >- The time at which the contact was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2025-07-09T02:24:16.193Z' updateTime: type: string format: date-time description: >- The time at which the contact was last updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2025-07-09T02:24:16.193Z' blocked: type: boolean description: Whether the contact is blocked. example: false customAttributes: type: object description: Contact's custom attributes as key-value pairs. additionalProperties: type: object example: company: YCloud Inc age: 25 preferences: newsletter: true ContactDeleted: type: object description: |- Represents a contact deleted event. Contains the contact information that was deleted. required: - id properties: id: type: string description: Contact ID example: '1824266594102064129' remarkName: type: string description: The business-managed remark name from the deleted contact snapshot. example: Former customer nickName: type: string description: Contact's nickname. example: Jane Smith phoneNumber: type: string description: >- Unique Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16475551234' updateTime: type: string format: date-time description: >- The time at which the contact was last updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2025-07-08T15:25:00.000Z' ContactNote: type: object description: >- Represents the customer-facing snapshot of a contact note without internal operator identifiers. required: - id - contactId - username - phoneNumber - content properties: id: type: string minLength: 24 maxLength: 24 pattern: ^[0-9a-fA-F]{24}$ example: 6a3de646e18f344f743aaa4d contactId: type: string example: '1824266594102064128' username: type: string nullable: true description: >- Username of the contact that owns this note, without the leading `@`. example: alice_01 phoneNumber: type: string nullable: true description: Phone number of the contact that owns this note in E.164 format. example: '+16315551111' content: type: string maxLength: 500 example: Customer prefers follow-up in the morning. createTime: type: string format: date-time updateTime: type: string format: date-time ContactUnsubscribeCreated: type: object description: Represents a customer initiates an unsubscribe event. required: - id properties: id: type: string description: Unique ID of the contact unsubscribe event. phoneNumber: type: string description: >- Unique Customer Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16475551234' source: type: string description: >- The source from which a customer initiates an unsubscribe. - `Whatsapp`: The customer initiated an unsubscribe on the whatsapp client. - `Inbox`:You added a customer to the unsubscribe list on the Inbox page of YCloud. - `Chatbot`: The message sent by the customer triggered the unsubscribe keyword configured by the Chatbot. - `API`: You add customers to the unsubscribe list through YCloud's OpenAPI. - `Manual`: You added a customer to the unsubscribe list on the Contact page of YCloud. enum: - Whatsapp - Inbox - Chatbot - API - Manual example: Whatsapp updateTime: type: string format: date-time description: >- The time when a customer initiates an unsubscribe, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2025-07-08T15:25:00.000Z' ContactUnsubscribeDeleted: type: object description: Represents a customer resumed their subscription event. required: - id properties: id: type: string description: Unique ID of the contact resubscribe event. phoneNumber: type: string description: >- Unique Customer Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16475551234' source: type: string description: >- The source from which a customer resumed their subscription - `Whatsapp`: The customer resumed their subscription on the whatsapp client - `API`: You remove the customer from the unsubscribe list through the OpenAPI of YCloud - `Manual`: You remove the customer from the unsubscribe list on the Contact page of YCloud. enum: - Whatsapp - API - Manual example: Whatsapp updateTime: type: string format: date-time description: >- The time when customers cancel unsubscribe, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2025-07-08T15:25:00.000Z' EmailDelivery: type: object description: Represents an email delivery report. required: - emailId - recipientAddress properties: emailId: type: string description: Unique ID for the related email you've previously sent. minLength: 6 maxLength: 128 recipientAddress: type: string description: A recipient's email address. example: tom@example.com status: type: string description: >- Delivery status of the email to the specific recipient address. - `sending`: The messaging request is accepted by our system. - `failed`: The message failed to be sent from our system. - `sent`: The message has been sent from our system. - `delivered`: Our system has received a delivery receipt indicating that message is delivered. - `undelivered`: Our system has received a delivery receipt indicating that message is not delivered. enum: - sending - failed - sent - delivered - undelivered example: failed errorCode: type: string description: Error code when the email is undeliverable. example: 402 errorMessage: type: string description: Error message when the email is undeliverable. example: Unsubscribes externalId: type: string description: The `externalId` you set when you sent the email. bizType: type: string description: >- This can be either empty or one of `email`, or `verify`. Defaults to `email`. - `email`: Indicates that the message is sent via the **Email** product. - `verify`: Indicates that the message is sent via the **Verify** product. example: email verificationId: type: string description: The verification ID. Included only when `bizType` is `verify`. example: VERIFICATION-ID Sms: type: object required: - id - to properties: id: type: string description: Unique ID for the object. minLength: 6 maxLength: 128 to: type: string description: >- The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' text: type: string description: The text of this message. example: Your verification code is 123456. senderId: type: string description: Sender ID to be used. example: Brand regionCode: type: string description: >- [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) example: US totalSegments: type: integer format: int32 minimum: 1 description: >- Number of message segments. See [SMS character encoding](https://helpdocs.ycloud.com/help-center/integrations/channels/global-sms/sms-basic-principles#sms-encoding) for more info. example: 1 totalPrice: type: number format: double description: Total price of this message. example: 0.0085 currency: type: string description: >- Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217). example: USD status: type: string description: >- Delivery status. One of `accepted`, `sent`, `delivered`, `undelivered`, or `failed`. - `accepted`: The messaging request is accepted by our system. - `failed`: The message failed to be sent from our system. - `sent`: The message has been sent from our system. - `delivered`: Our system has received a delivery receipt indicating that message is delivered. - `undelivered`: Our system has received a delivery receipt indicating that message is not delivered. example: sent enum: - accepted - failed - sent - delivered - undelivered errorCode: type: string description: Error code when the message is undeliverable. createTime: type: string format: date-time description: >- The time at which this message was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-03-01T12:00:00.000Z`. example: '2022-03-01T12:00:00.000Z' updateTime: type: string format: date-time description: >- The time at which the delivery report for this message was updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-03-01T12:00:00.000Z`. example: '2022-03-01T12:00:00.000Z' externalId: type: string description: >- 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. callbackUrl: type: string description: >- Delivery report URL. You can provide a URL, and we will push the updated status report to your server in time. e.g., https://httpbin.org/anything?tag=api. Note: We recommend configuring Webhook Endpoints instead. example: https://httpbin.org/anything?tag=api-sms bizType: type: string description: >- This can be either empty or one of `sms`, or `verify`. Defaults to `sms`. - `sms`: Indicates that the message is sent via the **SMS** product. - `verify`: Indicates that the message is sent via the **Verify** product. example: sms verificationId: type: string description: The verification ID. Included only when `bizType` is `verify`. example: VERIFICATION-ID SmsInbound: type: object description: >- Represents an inbound SMS message, which means a user replies to your message. properties: id: type: string description: Unique ID of the message. from: type: string description: >- The user's phone number who sent the message to your registered sender ID, formatted in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' to: type: string description: >- The receiver's phone number, which is one of your registered Sender IDs. text: type: string description: The text of this message. sendTime: type: string format: date-time description: >- The time at which this message was sent, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' Voice: type: object required: - id - to properties: id: type: string description: Unique ID for the object. minLength: 6 maxLength: 128 to: type: string description: >- The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' verificationCode: type: string description: The verification code to be sent, 4 to 6 digits. example: '123456' language: type: string description: >- [ISO 639 Language Code](https://www.iso.org/iso-639-language-codes.html). example: en regionCode: type: string description: >- [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). example: US totalSegments: type: integer format: int32 minimum: 1 description: Number of message segments. It's always 1 for voice calls. example: 1 totalPrice: type: number format: double description: Total price of this message. example: 0.05 currency: type: string description: >- Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217). example: USD status: type: string description: >- Delivery status. One of `accepted`, `sent`, `delivered`, `undelivered`, or `failed`. - `accepted`: The messaging request is accepted by our system. - `failed`: The message failed to be sent from our system. - `sent`: The message has been sent from our system. - `delivered`: Our system has received a delivery receipt indicating that message is delivered. - `undelivered`: Our system has received a delivery receipt indicating that message is not delivered. example: sent enum: - accepted - failed - sent - delivered - undelivered errorCode: type: string description: Error code when the message is undeliverable. createTime: type: string format: date-time description: >- The time at which this message was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-03-01T12:00:00.000Z`. example: '2022-03-01T12:00:00.000Z' updateTime: type: string format: date-time description: >- The time at which the delivery report for this message was updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-03-01T12:00:00.000Z`. example: '2022-03-01T12:00:00.000Z' externalId: type: string description: >- 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. callbackUrl: type: string description: >- Delivery report URL. You can provide a URL, and we will push the updated status report to your server in time. e.g., https://httpbin.org/anything?tag=api. Note: We recommend configuring Webhook Endpoints instead. example: https://httpbin.org/anything?tag=api-voice bizType: type: string description: >- This can be either empty or one of `voice`, or `verify`. Defaults to `voice`. - `voice`: Indicates that the message is sent via the **Voice** product. - `verify`: Indicates that the message is sent via **Verify** product. example: voice verificationId: type: string description: The verification ID. Included only when `bizType` is `verify`. example: VERIFICATION-ID WhatsappBusinessAccount: type: object description: >- Represents a specific [WhatsApp Business Account (WABA)](https://developers.facebook.com/docs/whatsapp/overview/business-accounts). properties: id: type: string description: WhatApp Business Account ID. name: type: string description: User-friendly name to differentiate WhatsApp Business Accounts. currency: type: string description: >- The currency in which the payment transactions for the WhatsApp Business Account will be processed. messageTemplateNamespace: type: string description: >- Namespace string for the message templates that belong to the WhatsApp Business Account. accountReviewStatus: $ref: '#/components/schemas/WhatsappBusinessAccountReviewStatus' businessVerificationStatus: $ref: '#/components/schemas/MetaBusinessAccountVerificationStatus' country: type: string description: >- Country of the WhatsApp Business Account's owning Meta Business account. ownershipType: type: string description: Ownership type of the WhatsApp Business Account. paymentMethodAttached: type: boolean description: >- Whether we have attached a payment method to the WhatsApp Business Account. primaryFundingId: type: string description: Primary funding ID for the WhatsApp Business Account paid service. purchaseOrderNumber: type: string description: >- The purchase order number supplied by the business for payment management purposes. timezoneId: type: string description: >- The timezone ID of the WhatsApp Business Account. See [Timezone IDs](https://developers.facebook.com/docs/marketing-api/reference/ad-account/timezone-ids). example: '1' decision: $ref: '#/components/schemas/WhatsappReviewDecision' description: >- Review decision made on this WhatsApp Business Account. One of `APPROVED` or `REJECTED`. updateEvent: $ref: '#/components/schemas/WhatsappBusinessAccountUpdateEventEnum' banState: $ref: '#/components/schemas/WhatsappBusinessAccountBanState' banDate: type: string description: The date when the WABA is banned. example: December 9, 2022 violationType: type: string description: >- Used to report violations imposed on the WABA. See also [WhatsApp Business Platform Policy Violations](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/violations). example: SCAM restrictions: type: array description: >- Used to report restrictions imposed on the WABA, when that WABA violates [WhatsApp Business Platform policies](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement). items: $ref: '#/components/schemas/WhatsappBusinessAccountRestrictionInfo' maxPhoneNumbersPerBusiness: type: integer format: int32 description: >- Included in a `whatsapp.business_account.updated` webhook with `updateEvent=BUSINESS_CAPABILITY_UPDATE` when Meta reports the Business Portfolio phone-number registration limit. Meta currently reports this field separately from `maxPhoneNumbersPerWaba`, but consumers must process both if a future update includes them together. example: 20 maxPhoneNumbersPerWaba: type: integer format: int32 description: >- Included in a `whatsapp.business_account.updated` webhook with `updateEvent=BUSINESS_CAPABILITY_UPDATE` when Meta reports the WABA phone-number registration limit. Meta currently reports this field separately from `maxPhoneNumbersPerBusiness`, but consumers must process both if a future update includes them together. example: 25 authIntlRateEligibilityCountries: type: array description: >- Starting June 1, 2024, we are updating our authentication rate card and introducing a new authentication-international rate. This rate will apply in the the following countries: - June 1, 2024 – Indonesia (country calling code +62, country code `ID`) - July 1, 2024 – India (country calling code +91, country code `IN`) See also [Authentication-International Rates](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates). items: $ref: '#/components/schemas/WhatsappAuthIntlRateEligibilityCountry' primaryBusinessLocation: type: string description: >- Your primary business location is the country where your business is based. It will appear in the Business Manager under the Primary Business Location field starting May 1, 2024. [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). example: US removedReason: type: string description: >- Raw reason from the WhatsApp Business Account deletion event. Known values include: - `ACCOUNT_DISCONNECTED`: The account was disconnected due to enforcement or because the WhatsApp account was explicitly deleted. - `BUSINESS_DOWNGRADE`: The phone number was registered with the consumer WhatsApp app. - `CHANGE_NUMBER`: The WhatsApp phone number was changed. - `COMPANION_INACTIVITY`: A companion device was inactive for approximately 30 days. - `PRIMARY_INACTIVITY`: A primary device was inactive for approximately 30 days. - `USER_RE_REGISTERED`: WhatsApp was re-registered on a new device. Unknown values are returned as received. example: ACCOUNT_DISCONNECTED removedInitiatedBy: type: string description: >- Raw initiator from the WhatsApp Business Account deletion event. Known values include: - `USER`: The removal was initiated by the WhatsApp user. - `SYSTEM`: The removal was initiated by the Meta system. Unknown values are returned as received. example: USER removedTime: type: string format: date-time description: >- The time when the WhatsApp Business Account deletion event was received, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2026-05-19T12:00:00.000Z`. example: '2026-05-19T12:00:00.000Z' WhatsappInboundMessage: type: object description: WhatsApp inbound message object. required: - id properties: id: type: string description: Unique ID for the object. wamid: type: string description: The original message ID on WhatsApp's platform. example: wamid.BgNODYxN... wabaId: type: string description: WhatsApp Business Account ID. example: whatsapp-business-account-id from: type: string description: >- The customer's phone number who sent the message to the business, formatted in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' fromUserId: type: string description: The customer's WhatsApp Business-scoped user ID (BSUID). example: US.1234 fromParentUserId: type: string description: The customer's parent WhatsApp Business-scoped user ID. example: US.ENT.1234 customerProfile: $ref: '#/components/schemas/WhatsappProfile' description: The customer's profile information. to: type: string description: >- The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' sendTime: type: string format: date-time description: >- The time at which this message is sent, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' type: $ref: '#/components/schemas/WhatsappInboundMessageType' text: $ref: '#/components/schemas/WhatsappInboundMessageText' image: $ref: '#/components/schemas/WhatsappInboundMessageMedia' video: $ref: '#/components/schemas/WhatsappInboundMessageMedia' audio: $ref: '#/components/schemas/WhatsappInboundMessageMedia' document: $ref: '#/components/schemas/WhatsappInboundMessageMedia' sticker: $ref: '#/components/schemas/WhatsappInboundMessageMedia' interactive: $ref: '#/components/schemas/WhatsappInboundMessageInteractive' location: $ref: '#/components/schemas/WhatsappInboundMessageLocation' button: $ref: '#/components/schemas/WhatsappInboundMessageButton' contacts: type: array items: $ref: '#/components/schemas/WhatsappMessageContact' reaction: $ref: '#/components/schemas/WhatsappMessageReaction' order: $ref: '#/components/schemas/WhatsappInboundMessageOrder' system: $ref: '#/components/schemas/WhatsappInboundMessageSystem' errors: type: array items: $ref: '#/components/schemas/WhatsappInboundMessageError' context: $ref: '#/components/schemas/WhatsappInboundMessageContext' referral: $ref: '#/components/schemas/WhatsappInboundMessageReferral' groupId: type: string description: >- WhatsApp group ID. This field is included when the inbound message is sent in a WhatsApp group. example: 120363345678901234@g.us MetaBusinessAgentWebhook: type: object description: |- Payload for whatsapp.meta_business_agent.handover.updated. Currently emitted only for Agents onboarded through the Public REST API, not Console-created Agents. Null fields are omitted. properties: agentId: type: string description: YCloud Agent ID. Not a Meta Agent ID or an Inbox assignee ID. example: 00000000-0000-4000-8000-000000000001 metaAgentId: type: string description: Meta Agent ID, when available. example: META_AGENT_ID phoneNumberId: type: string description: Meta business phone number ID. Not an E.164 phone number. example: PHONE_NUMBER_ID wabaId: type: string description: >- WhatsApp Business Account ID from the source callback, when available. example: WABA_ID consumerPhoneNumber: type: string description: >- Consumer phone number from the handover callback, normalized to E.164 when available. This is not the business number or phoneNumberId. pattern: ^\+[1-9][0-9]{7,14}$ example: '+12025550124' controlState: type: string description: >- Present for handover events. Currently APP_CONTROL_TAKEN for Public REST API handover callbacks. Does not confirm an Inbox assignment or message delivery. example: APP_CONTROL_TAKEN actor: type: string description: >- Optional handover source actor. For a control_passed handoff this is the previous owner app ID, not the employee who receives the conversation. example: PREVIOUS_OWNER_APP_ID reason: type: string description: >- Optional provider handover reason or metadata, for example customer_request. Not a closed enum. example: customer_request timestamp: type: integer format: int64 description: >- Source event time in Unix milliseconds, or processing time if unavailable. example: 1788919204000 WhatsappGroupWebhook: type: object description: WhatsApp group webhook payload. properties: wabaId: type: string description: WhatsApp Business Account ID. example: '123456789012345' displayPhoneNumber: type: string description: The display phone number from WhatsApp webhook metadata. example: '16315551111' phoneNumberId: type: string description: WhatsApp phone number ID. example: '1234567890123456' field: $ref: '#/components/schemas/WhatsappGroupWebhookField' type: $ref: '#/components/schemas/WhatsappGroupWebhookType' requestId: type: string description: The request ID returned by an asynchronous group API operation. example: REQ_1 status: $ref: '#/components/schemas/WhatsappGroupWebhookStatus' groupId: type: string description: WhatsApp group ID. example: 120363345678901234@g.us messageId: type: string description: >- YCloud group-message ID. Present only when the status event is linked to a saved outbound group message. example: wam_group_01 inviteLink: type: string description: The group invite link. example: https://chat.whatsapp.com/AbCdEfGhIjK reason: type: string description: The reason for a participant, join request, or removal event. example: invite_link initiatedBy: type: string description: Indicates who initiated a participant removal event. enum: - business - participant example: business joinRequestId: type: string description: The join request ID. example: join-request-id waId: type: string description: WhatsApp user ID for a single participant event. example: '16315551111' recipientUserId: type: string description: Business-scoped user ID for a single participant event. example: US.1234 parentRecipientUserId: type: string description: Parent business-scoped user ID for a single participant event. example: US.parent123 customerProfile: $ref: '#/components/schemas/WhatsappGroupCustomerProfile' subject: type: string description: The group subject. example: New Purchase Inquiry description: type: string description: The group description. example: Group for purchase inquiries. joinApprovalMode: $ref: '#/components/schemas/WhatsappGroupJoinApprovalMode' addedParticipants: type: array description: Participants added to the group. items: $ref: '#/components/schemas/WhatsappGroupWebhookParticipant' removedParticipants: type: array description: Participants removed from the group. items: $ref: '#/components/schemas/WhatsappGroupWebhookParticipant' failedParticipants: type: array description: Participants that failed to be added or removed. items: $ref: '#/components/schemas/WhatsappGroupWebhookParticipant' settings: type: array description: Group setting update details. items: $ref: '#/components/schemas/WhatsappGroupWebhookSetting' errors: type: array description: Errors returned by WhatsApp. items: type: object additionalProperties: true contacts: type: array description: Contacts included in group message status webhooks. items: $ref: '#/components/schemas/WhatsappGroupWebhookStatusContact' statuses: type: array description: Group message status details. items: $ref: '#/components/schemas/WhatsappGroupWebhookMessageStatus' webhookTime: type: string format: date-time description: The time at which WhatsApp triggered this webhook. example: '2026-05-13T00:00:00.000Z' dedupeKey: type: string description: Idempotency key for deduplicating group webhook events. example: WABA_ID|REQ_1|group_lifecycle_update|group_create|created WhatsappPhoneNumber: type: object description: >- See [WhatsApp Business Phone Number](https://developers.facebook.com/docs/whatsapp/cloud-api/phone-numbers) properties: id: type: string description: Phone number ID. example: '1234567890123456' phoneNumber: type: string description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' displayPhoneNumber: type: string description: Display phone number. example: +1 631-555-1111 wabaId: type: string description: WhatsApp Business Account ID. example: whatsapp-business-account-id businessUsername: type: string description: >- Active Business Username for this phone number. The value is a plain username without `@`. example: acme.support businessUsernameStatus: $ref: '#/components/schemas/WhatsappBusinessUsernameStatus' requestedBusinessUsername: type: string description: >- Last requested Business Username that is still under review. This value can coexist with an active `businessUsername` while the new request is pending. example: acme.help businessUsernameUpdatedAt: type: string format: date-time description: The time when the Business Username state was last updated. example: '2026-05-26T12:00:00.000Z' qualityRating: $ref: '#/components/schemas/WhatsappPhoneNumberQualityRating' messagingLimit: type: string description: >- Messaging limits determine the maximum number of business-initiated conversations each phone number can start in a rolling 24-hour period. See also [Messaging Limits](https://developers.facebook.com/docs/whatsapp/messaging-limits). - `TIER_NOT_SET`: Unknown limit. - `TIER_50`: 50 business-initiated conversations in a rolling 24-hour period. - `TIER_250`: 250 business-initiated conversations in a rolling 24-hour period. - `TIER_1K`: 1K business-initiated conversations with unique customers in a rolling 24-hour period. - `TIER_10K`: 10K business-initiated conversations with unique customers in a rolling 24-hour period. - `TIER_100K`: 100K business-initiated conversations with unique customers in a rolling 24-hour period. - `TIER_UNLIMITED`: An unlimited number of business-initiated conversations in a rolling 24-hour period. example: TIER_1K whatsappBusinessManagerMessagingLimit: type: string description: >- The owning business portfolio's messaging limit. Starting October 7, 2025, messaging limits will instead be calculated and set on a business portfolio basis, and will be shared by all business phone numbers within each portfolio. See also [phone_number_quality_update webhook reference](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/reference/phone_number_quality_update). - `TIER_NOT_SET`: The business phone number has not been used to send a message yet. - `TIER_50`: Messaging limit of 50 business-initiated conversations in a rolling 24-hour period. - `TIER_250`: Messaging limit of 250 business-initiated conversations in a rolling 24-hour period. - `TIER_2K`: Messaging limit of 2,000 business-initiated conversations in a rolling 24-hour period. - `TIER_10K`: Messaging limit of 10,000 business-initiated conversations in a rolling 24-hour period. - `TIER_100K`: Messaging limit of 100,000 business-initiated conversations in a rolling 24-hour period. - `TIER_UNLIMITED`: The business phone number has higher throughput with unlimited business-initiated conversations. verifiedName: type: string description: Verified name. example: John’s Cake Shop codeVerificationStatus: $ref: '#/components/schemas/WhatsappPhoneNumberCodeVerificationStatus' isOfficialBusinessAccount: type: boolean description: >- Whether this phone number is an official business account or not. An official business account has a green checkmark badge in its profile and chat thread headers. See [Official Business Account](https://developers.facebook.com/docs/whatsapp/overview/business-accounts#official-business-account) for more information. status: $ref: '#/components/schemas/WhatsappPhoneNumberStatus' nameStatus: $ref: '#/components/schemas/WhatsappPhoneNumberNameStatus' newNameStatus: $ref: '#/components/schemas/WhatsappPhoneNumberNameStatus' description: >- The review status of the new display name request. See also [Get Display Name Status](https://developers.facebook.com/docs/whatsapp/business-management-api/manage-phone-numbers#get-display-name-status--beta-). decision: $ref: '#/components/schemas/WhatsappReviewDecision' description: >- Review decision made on this phone number. One of `APPROVED` or `REJECTED`. requestedVerifiedName: type: string description: Last requested verified name. rejectionReason: type: string description: Rejection reason. qualityUpdateEvent: $ref: '#/components/schemas/WhatsappPhoneNumberQualityUpdateEventEnum' updateEvent: type: string description: Account update event that triggered this phone number status change. enum: - ACCOUNT_RECONNECTED - ACCOUNT_OFFBOARDED example: ACCOUNT_OFFBOARDED throughputLevel: type: string description: >- Current Meta throughput level of the WhatsApp phone number. - `STANDARD`: Default Cloud API throughput level, currently up to 80 messages per second. - `HIGH`: Upgraded Cloud API throughput level, currently up to 1,000 messages per second, subject to Meta's current Cloud API throughput rules. - `NOT_APPLICABLE`: Throughput level is not applicable to this phone number. enum: - STANDARD - HIGH - NOT_APPLICABLE example: HIGH WhatsappPayment: type: object description: >- Represents a payment object. Businesses receive updates via webhooks when the status of the user-initiated transaction changes. required: - wabaId - referenceId - status properties: wabaId: type: string description: WhatsApp Business Account ID. referenceId: type: string description: >- Unique identifier for the payment provided by the business. It is case sensitive and cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters. status: $ref: '#/components/schemas/WhatsappPaymentStatus' transactions: type: array description: Contains the latest transaction attempt for this payment. items: $ref: '#/components/schemas/WhatsappPaymentTransaction' WhatsappTemplate: type: object description: >- See [WhatsApp Templates](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates). required: - wabaId - name - language properties: officialTemplateId: type: string description: >- Official template ID assigned by WhatsApp. This ID is used to identify the template in WhatsApp's system. example: official-template-id wabaId: type: string description: WhatsApp Business Account ID. example: whatsapp-business-account-id name: type: string description: Name of the template. maxLength: 512 pattern: '[a-z0-9]{1,512}' language: type: string description: >- Language code of the template. See [Supported Languages](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/supported-languages) for all codes. example: en_US category: $ref: '#/components/schemas/WhatsappTemplateCategory' subCategory: $ref: '#/components/schemas/WhatsappTemplateSubCategory' previousCategory: type: string description: >- This field indicates the template's previous category (or `null`, for newly created templates after April 1, 2023). Compare this value to the template's `category` field value, which indicates the template's current category. messageSendTtlSeconds: type: integer format: int32 description: >- If we are unable to deliver a message for an amount of time that exceeds its time-to-live, we will stop retrying and drop the message. By default, messages that use an authentication template have a default TTL of **10 minutes**, and messages that use a utility or marketing template have a default TTL of **30 days**. Set its value between `30` and `900` seconds (i.e., 30 seconds to 15 minutes) for authentication templates, or `30` and `43200` seconds (i.e., 30 seconds to 12 hours) for utility templates, or `43200` and `2592000` seconds (i.e., 12 hours to 30 days) for marketing templates. Alternatively, you can set this value to `-1`, which will set a custom TTL of 30 days for either type of template. We encourage you to set a time-to-live for all of your authentication templates, preferably equal to or less than your code expiration time, to ensure your customers only get a message when a code is still usable. Authentication templates created before October 23, 2024, have a default TTL of 30 days. example: 600 components: type: array description: >- Template components. A template consists of `HEADER`, `BODY`, `FOOTER`, and `BUTTONS` components. `BODY` component is required, the other types are optional. minItems: 1 items: $ref: '#/components/schemas/WhatsappTemplateComponent' status: $ref: '#/components/schemas/WhatsappTemplateStatus' qualityRating: $ref: '#/components/schemas/WhatsappTemplateQualityRating' reason: type: string description: The reason why the template is rejected. createTime: type: string format: date-time description: >- The time at which this object is created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' updateTime: type: string format: date-time description: >- The time at which this object is updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' statusUpdateEvent: $ref: '#/components/schemas/WhatsappTemplateStatusUpdateEventEnum' description: >- The WhatsApp template status update event that caused this webhook. For `ARCHIVED`, the template `status` is `ARCHIVED`. For `UNARCHIVED`, the template `status` is the current status returned by Meta, for example `APPROVED`; it does not represent a new approval review. disableDate: type: string description: >- The date at which the template will be disabled. When a WhatsApp template `FLAGGED` event is received, this field is set. example: December 9, 2022 whatsappApiError: $ref: '#/components/schemas/WhatsappApiError' CallingConnect: type: object description: >- Represents a WhatsApp call connect event. Contains information about the call connection including SDP details and participant information. required: - id - wacid properties: id: type: string description: Unique ID for the call event. example: call_evt_123456789 wacid: type: string description: The WhatsApp call ID. This ID uniquely identifies the call session. example: wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh phoneId: type: string description: The WhatsApp Business phone number ID. example: '436666719526789' from: type: string description: >- The caller's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' fromUserId: type: string description: >- The caller's WhatsApp Business-scoped user ID (BSUID) for customer-initiated calls. example: US.1234 fromParentUserId: type: string description: >- The caller's parent WhatsApp Business-scoped user ID for customer-initiated calls. example: US.ENT.1234 to: type: string description: >- The callee's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551112' toUserId: type: string description: >- The callee's WhatsApp Business-scoped user ID (BSUID) for business-initiated calls. example: US.1234 toParentUserId: type: string description: >- The callee's parent WhatsApp Business-scoped user ID for business-initiated calls. example: US.ENT.1234 customerProfile: $ref: '#/components/schemas/WhatsappProfile' description: >- The customer's profile information, including WhatsApp username when available. direction: type: string description: >- The direction of the call. - `USER_INITIATED`: Call initiated by the customer to the business. - `BUSINESS_INITIATED`: Call initiated by the business to the customer. enum: - USER_INITIATED - BUSINESS_INITIATED example: USER_INITIATED sdpType: type: string description: The SDP type for the WebRTC connection. enum: - offer - answer example: offer sdp: type: string description: >- The Session Description Protocol (SDP) information compliant with [RFC 8866](https://datatracker.ietf.org/doc/html/rfc8866). Contains media session parameters for the WebRTC connection. example: "v=0\r\no=- 123456789 987654321 IN IP4 192.168.1.1\r\ns=-\r\nt=0 0\r\n..." dialTime: type: integer format: int64 description: The time when the call was dialed, in Unix timestamp milliseconds. example: 1640995200000 CallingTerminate: type: object description: >- Represents a WhatsApp call terminate event. Contains information about the call termination including duration and status. required: - id - wacid properties: id: type: string description: Unique ID for the call event. example: call_evt_123456789 wacid: type: string description: The WhatsApp call ID. This ID uniquely identifies the call session. example: wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh phoneId: type: string description: The WhatsApp Business phone number ID. example: '436666719526789' from: type: string description: >- The caller's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' fromUserId: type: string description: >- The caller's WhatsApp Business-scoped user ID (BSUID) for customer-initiated calls. example: US.1234 fromParentUserId: type: string description: >- The caller's parent WhatsApp Business-scoped user ID for customer-initiated calls. example: US.ENT.1234 to: type: string description: >- The callee's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551112' toUserId: type: string description: >- The callee's WhatsApp Business-scoped user ID (BSUID) for business-initiated calls. example: US.1234 toParentUserId: type: string description: >- The callee's parent WhatsApp Business-scoped user ID for business-initiated calls. example: US.ENT.1234 customerProfile: $ref: '#/components/schemas/WhatsappProfile' description: >- The customer's profile information, including WhatsApp username when available. direction: type: string description: >- The direction of the call. - `USER_INITIATED`: Call initiated by the customer to the business. - `BUSINESS_INITIATED`: Call initiated by the business to the customer. enum: - USER_INITIATED - BUSINESS_INITIATED example: USER_INITIATED startTime: type: integer format: int64 description: The time when the call started, in Unix timestamp milliseconds. example: 1640995200000 endTime: type: integer format: int64 description: The time when the call ended, in Unix timestamp milliseconds. example: 1640995320000 duration: type: integer format: int64 description: The duration of the call in seconds. example: 120 status: type: string description: |- The final status of the call. - `COMPLETED`: The call was successfully completed. - `FAILED`: The call failed due to an error. enum: - COMPLETED - FAILED example: COMPLETED errorCode: type: string description: >- Error code when the call status is `FAILED`. Numeric string representing the error. example: '131000' CallingStatusUpdated: type: object description: |- Represents a WhatsApp call status update event. Contains information about status changes during the call lifecycle. required: - wacid - status properties: id: type: string description: Unique ID for the call event (optional field, may not be present). example: call_evt_123456789 wabaId: type: string description: WhatsApp Business Account ID. example: '188234691048809' wacid: type: string description: The WhatsApp call ID. This ID uniquely identifies the call session. example: wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE phoneId: type: string description: >- The WhatsApp Business phone number ID (optional field, may not be present). example: '436666719526789' status: type: string description: |- The current status of the call. - `RINGING`: Business initiated call is ringing the user. - `ACCEPTED`: Business initiated call is accepted by the user. - `REJECTED`: Business initiated call is rejected by the user. enum: - RINGING - ACCEPTED - REJECTED example: RINGING recipientPhone: type: string description: >- The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+6281361905133' recipientUserId: type: string description: The recipient's WhatsApp Business-scoped user ID (BSUID). example: US.1234 parentRecipientUserId: type: string description: The recipient's parent WhatsApp Business-scoped user ID. example: US.ENT.1234 customerProfile: $ref: '#/components/schemas/WhatsappProfile' description: >- The customer's profile information, including WhatsApp username when available. CallingMediaUpdated: type: object additionalProperties: false description: >- Terminal recording or transcription state for an API-sourced WhatsApp call. required: - wacid - phoneId - mediaAssetId - status properties: wacid: type: string description: WhatsApp call ID. example: wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE phoneId: type: string description: >- WhatsApp business phone number ID used for authorized-asset delivery. example: '461269257068832' mediaAssetId: type: string description: YCloud media asset ID used with the call media download API. example: 66b1f0c2e4b05c2d8f1a3b47 status: type: string enum: - AVAILABLE - FAILED example: AVAILABLE error: type: object additionalProperties: false description: Present only when `status` is `FAILED`. required: - code - retryable properties: code: type: string description: Stable failure code. example: CALLING_RECORDING_PROCESSING_FAILED retryable: type: boolean description: Whether retrying the upstream media operation may succeed. example: false WhatsappFlowStatusChange: type: object description: >- Represents a WhatsApp flow status change event. Contains information about the flow status change including the flow ID and the new status. required: - flowId - wabaId - newStatus properties: flowId: type: string description: The unique ID of the Flow. example: '1097420589034000' wabaId: type: string description: WhatsApp Business Account ID. message: type: string description: The message ID of the flow status change. example: Flow Webhook 3 changed status from DRAFT to PUBLISHED oldStatus: type: string description: The old status of the flow. example: DRAFT newStatus: type: string description: The new status of the flow. example: PUBLISHED WhatsappUserPreference: properties: wabaId: type: string description: WhatsApp Business Account ID. example: 1234123123 businessPhoneNumber: type: string description: Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' businessPhoneId: type: string description: Phone number ID. example: '1234567890123456' contactName: type: string description: WhatsApp user name. example: John contactPhoneNumber: type: string description: >- WhatsApp user phone number. Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' userId: type: string description: The WhatsApp user's Business-scoped user ID (BSUID). example: US.13491208655302741918 parentUserId: type: string description: >- The WhatsApp user's parent Business-scoped user ID. Omitted when parent BSUIDs are not enabled. example: US.ENT.11815799212886844830 detail: type: string description: Description of marketing message preference. example: User requested to stop marketing messages category: type: string example: marketing_messages value: type: string description: Marketing message preference. example: stop timestamp: type: string description: Unix timestamp indicating when the webhook was triggered. example: '1739321024000' WhatsappEchoMessage: type: object description: >- WhatsApp outbound message subset emitted for Agent echo events. Fields are copied from the source echo or status callback; unavailable values are omitted. Agent, control, routing, pricing, and conversation fields are never included. required: - id properties: id: type: string description: >- YCloud message ID. Use it to correlate created and updated echo events. wamid: type: string description: The original message ID on WhatsApp's platform, when available. example: wamid.EXAMPLE wabaId: type: string description: >- WhatsApp Business Account ID from the source callback, when available. example: WABA_ID from: type: string description: Business sender number in E.164 format, when available. example: '+12025550123' to: type: string description: >- Recipient number in E.164 format when the callback identifies the customer by phone number. example: '+12025550124' recipientUserId: type: string description: >- Recipient WhatsApp Business-scoped user ID (BSUID), when supplied by the callback. example: GB.898232076600896 parentRecipientUserId: type: string description: >- Recipient parent WhatsApp Business-scoped user ID, when supplied by the callback. example: GB.ENT.898232076600896 type: type: string description: >- Message type copied from a supported provider callback. Current values include text, interactive, image, video, audio, document, sticker, location, contacts, and reaction. Clients should tolerate future values. example: text text: $ref: '#/components/schemas/WhatsappMessageText' image: $ref: '#/components/schemas/WhatsappEchoMessageMedia' video: $ref: '#/components/schemas/WhatsappEchoMessageMedia' audio: $ref: '#/components/schemas/WhatsappEchoMessageMedia' document: $ref: '#/components/schemas/WhatsappEchoMessageMedia' sticker: $ref: '#/components/schemas/WhatsappEchoMessageMedia' location: $ref: '#/components/schemas/WhatsappMessageLocation' interactive: $ref: '#/components/schemas/WhatsappMessageInteractive' contacts: type: array items: $ref: '#/components/schemas/WhatsappMessageContact' reaction: $ref: '#/components/schemas/WhatsappMessageReaction' context: $ref: '#/components/schemas/WhatsappMessageContext' status: $ref: '#/components/schemas/WhatsappMessageStatus' errorCode: type: string description: >- Source error code when status is failed and the provider supplied one. example: '131000' errorMessage: type: string description: >- Source error title when status is failed and the provider supplied one. example: Provider failure createTime: type: string format: date-time description: Source echo time for a created event, formatted in RFC 3339. example: '2026-09-09T02:00:00.000Z' updateTime: type: string format: date-time description: Source status time for an updated event, formatted in RFC 3339. example: '2026-09-09T02:00:01.000Z' sendTime: type: string format: date-time description: >- Source echo time on created events, or source status time when the current event reports sent. example: '2026-09-09T02:00:00.000Z' deliverTime: type: string format: date-time description: Source status time when the current event reports delivered. example: '2026-09-09T02:00:01.000Z' readTime: type: string format: date-time description: Source status time when the current event reports read. example: '2026-09-09T02:00:02.000Z' WhatsappMessage: type: object description: WhatsApp outbound message object. required: - id - wabaId - from properties: id: type: string description: Unique ID of the message. wamid: type: string description: The original message ID on WhatsApp's platform. example: wamid.BgNODYxN... wabaId: type: string description: WhatsApp Business Account ID. example: whatsapp-business-account-id from: type: string description: >- The sender's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' to: type: string description: >- The recipient's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. example: '+16315551111' recipient: type: string description: >- The recipient value submitted in the request when a BSUID or parent BSUID was used. example: US.1234 recipientUserId: type: string description: The recipient's WhatsApp Business-scoped user ID (BSUID). example: US.1234 toUserId: type: string description: Alias of `recipientUserId` kept for compatibility. example: US.1234 parentRecipientUserId: type: string description: The recipient's parent WhatsApp Business-scoped user ID. example: US.parent123 toParentUserId: type: string description: Alias of `parentRecipientUserId` kept for compatibility. example: US.parent123 customerProfile: $ref: '#/components/schemas/WhatsappProfile' description: >- The recipient's profile information, including WhatsApp username when available. conversation: $ref: '#/components/schemas/WhatsappConversation' description: >- 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](https://developers.facebook.com/docs/whatsapp/pricing). type: $ref: '#/components/schemas/WhatsappMessageType' template: $ref: '#/components/schemas/WhatsappMessageTemplate' text: $ref: '#/components/schemas/WhatsappMessageText' image: $ref: '#/components/schemas/WhatsappMessageMedia' video: $ref: '#/components/schemas/WhatsappMessageMedia' audio: $ref: '#/components/schemas/WhatsappMessageMedia' document: $ref: '#/components/schemas/WhatsappMessageMedia' sticker: $ref: '#/components/schemas/WhatsappMessageMedia' location: $ref: '#/components/schemas/WhatsappMessageLocation' interactive: $ref: '#/components/schemas/WhatsappMessageInteractive' contacts: type: array items: $ref: '#/components/schemas/WhatsappMessageContact' reaction: $ref: '#/components/schemas/WhatsappMessageReaction' context: $ref: '#/components/schemas/WhatsappMessageContext' externalId: type: string description: >- 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. category: type: string description: >- The Direct Send category, such as `utility` or `authentication`, when applicable. example: utility ttlSeconds: type: integer description: >- The configured Direct Send message lifetime in seconds, when applicable. example: 600 status: $ref: '#/components/schemas/WhatsappMessageStatus' errorCode: type: string description: Error code when the message status is `failed`. example: INTERNAL_SERVER_ERROR errorMessage: type: string description: Error message when the message status is `failed`. createTime: type: string format: date-time description: >- The time at which this message is created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' updateTime: type: string format: date-time description: >- The time at which this message is updated, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' sendTime: type: string format: date-time description: >- The time at which this message `status` changed to `sent`, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' deliverTime: type: string format: date-time description: >- The time at which this message `status` changed to `delivered`, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' readTime: type: string format: date-time description: >- The time at which this message `status` changed to `read`, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' totalPrice: type: number format: double description: >- 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 currency: type: string description: >- Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217). example: USD regionCode: type: string description: >- The [region code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the recipient phone number. example: US pricingCategory: $ref: '#/components/schemas/WhatsappPricingCategory' description: >- 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`.** pricingModel: $ref: '#/components/schemas/WhatsappPricingModel' description: |- The pricing model of the message. - `PMP`: Per-message pricing applies. - `CBP`: Conversation-based pricing applies. pricingType: $ref: '#/components/schemas/WhatsappPricingType' description: >- 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. whatsappApiError: $ref: '#/components/schemas/WhatsappApiError' bizType: type: string description: >- 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 verificationId: type: string description: The verification ID. Included only when `bizType` is `verify`. example: VERIFICATION-ID ContactAttributeChange: type: object description: >- Represents a single attribute change, containing the old value, new value, and change actions. properties: oldValue: description: >- The previous value of the attribute before the change. Can be a string, number, array, or boolean depending on the attribute type. This field is not included when the value is null. example: previous_value newValue: description: >- The new value of the attribute after the change. Can be a string, number, array, or boolean depending on the attribute type. This field is not included when the value is null. example: - tag1 - tag2 extra: type: array description: >- An array of change actions that describe what operations were performed on this attribute. items: $ref: '#/components/schemas/AttributeChangeAction' WhatsappBusinessAccountReviewStatus: type: string description: WhatsApp Business Account review status. enum: - PENDING - APPROVED - REJECTED MetaBusinessAccountVerificationStatus: type: string description: >- Current status of business verification of Meta Business Account which owns this WhatsApp Business Account. enum: - expired - failed - ineligible - not_verified - pending - pending_need_more_info - pending_submission - rejected - revoked - verified WhatsappReviewDecision: type: string description: >- Used if a decision about WhatsApp accounts or phone numbers has been made. enum: - APPROVED - REJECTED WhatsappBusinessAccountUpdateEventEnum: type: string description: >- Indicates the update event type of the WABA when a notification is sent to you to report a [policy violation](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement), a WABA has been banned and more. - `DISABLED_UPDATE`: WhatsApp Business Account Banned. - `ACCOUNT_RESTRICTION`: WhatsApp Business Account Restricted Due To Policy Violations. - `ACCOUNT_VIOLATION`: WhatsApp Business Account Violates Policy. - `PARTNER_REMOVED`: WhatsApp Business Account was removed from the partner connection. - `PARTNER_APP_UNINSTALLED`: WhatsApp Business Account partner app was uninstalled. - `AUTH_INTL_PRICE_ELIGIBILITY_UPDATE`: WhatsApp Business Account is eligible for the [authentication-international rate](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates). - `BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE`: Business's [primary business location](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates#primary-business-location) is set. - `BUSINESS_CAPABILITY_UPDATE`: Meta reported a change to the Business Portfolio or WABA phone-number registration limit. enum: - DISABLED_UPDATE - ACCOUNT_RESTRICTION - ACCOUNT_VIOLATION - PARTNER_REMOVED - PARTNER_APP_UNINSTALLED - AUTH_INTL_PRICE_ELIGIBILITY_UPDATE - BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE - BUSINESS_CAPABILITY_UPDATE WhatsappBusinessAccountBanState: type: string description: The ban state of the WhatsApp Business Account. enum: - SCHEDULE_FOR_DISABLE - DISABLE - REINSTATE WhatsappBusinessAccountRestrictionInfo: type: object description: >- Used to report restrictions imposed on a specific WABA, when that WABA violates [WhatsApp Business Platform policies](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement). properties: restrictionType: type: string description: Restriction type. enum: - RESTRICTED_ADD_PHONE_NUMBER_ACTION - RESTRICTED_BIZ_INITIATED_MESSAGING - RESTRICTED_CUSTOMER_INITIATED_MESSAGING - RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES expiration: type: string format: date-time description: >- The time at which this restriction expires, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' WhatsappAuthIntlRateEligibilityCountry: type: object description: >- Starting June 1, 2024, we are updating our authentication rate card and introducing a new authentication-international rate. This rate will apply in the the following countries: - June 1, 2024 – Indonesia (country calling code +62, country code `ID`) - July 1, 2024 – India (country calling code +91, country code `IN`) See also [Authentication-International Rates](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates). properties: countryCode: type: string description: >- [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). example: IN startTime: type: string format: date-time description: >- Date when newly-opened authentication conversations are subject to authentication-international rates, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2024-07-01T00:00:00.000Z`. example: '2024-07-01T00:00:00.000Z' WhatsappProfile: type: object description: Represents the profile of a WhatsApp account. properties: name: type: string description: Name of the WhatsApp account. example: John username: type: string description: WhatsApp username. example: john_doe WhatsappInboundMessageType: type: string description: >- WhatsApp inbound message type. See also [WhatsApp webhook messages object](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components#messages-object). enum: - text - image - video - audio - document - sticker - contacts - location - interactive - button - reaction - request_welcome - order - system - unsupported WhatsappInboundMessageText: type: object description: >- When the notification describes a text message, the text object provides the body of the text message. properties: body: type: string description: Message text. WhatsappInboundMessageMedia: type: object description: >- When a message with media (`image` | `document` | `audio` | `video` | `sticker`) is received, the WhatsApp Business API client will download the media. Once the media is downloaded, a notification is sent to your Webhook. This message contains information that identifies the media object and enables you to find and download the object. properties: id: type: string description: >- ID of the media. Can be used to delete the media if stored locally on the client. link: type: string description: >- The url to download the media file. Note that This link can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an `X-API-Key` header to download this file within a month. caption: type: string description: The provided caption for the media. Only present if specified. filename: type: string description: >- Filename on the sender's device. This will only be present in `document` media messages. metadata: type: object additionalProperties: type: object description: Metadata pertaining to `sticker` media. mime_type: type: string description: Mime type of the media. sha256: type: string description: Checksum. WhatsappInboundMessageInteractive: type: object description: >- When a customer has interacted with your message, this object is included in the message object. properties: type: type: string description: >- The type of interactive message received. - `button_reply`: Sent when a customer clicks a button. - `list_reply`: Sent when a customer selects an item from a list. - `nfm_reply`: Sent when a customer responds to a WhatsApp Flow (Next Feature Messaging). - `call_permission_reply`: Sent when a customer responds to a call permission request. enum: - button_reply - list_reply - nfm_reply - call_permission_reply button_reply: type: object description: >- Sent when a customer clicks a button. Returned when `type` is `button_reply`. properties: id: type: string description: Unique ID of the clicked button. title: type: string description: Title of a button. list_reply: type: object description: >- Sent when a customer selects an item from a list. Returned when `type` is `list_reply`. properties: id: type: string description: Unique ID of the selected list item. title: type: string description: Title of the selected list item. description: type: string description: Description of the selected row. nfm_reply: type: object description: >- Sent when a customer responds to a WhatsApp Flow (Next Feature Messaging). Returned when `type` is `nfm_reply`. properties: name: type: string description: The name of the flow or form being replied to. example: flow response_json: type: string description: >- JSON string containing the user's responses to the flow. Contains form field values and flow token. example: >- {"flow_token":"unused","screen_0_firstName_0":"王","screen_1_TextInput_1":"123","screen_1_TextInput_0":"11","screen_0_lastName_1":"TESTNAME"} body: type: string description: The body content of the flow reply message. example: Sent call_permission_reply: type: object description: >- Sent when a customer responds to a call permission request. Returned when `type` is `call_permission_reply`. This occurs when WhatsApp prompts users to grant callback permissions after they call your business. properties: response: type: string description: |- The customer's response to the call permission request. - `accept`: User granted permission for business to call back - `reject`: User rejected permission for business to call back enum: - accept - reject example: accept expiration_timestamp: type: integer format: int64 description: >- The timestamp (in seconds) when the call permission expires. Only present when response is "accept" and is_permanent is false. example: 1672531200 is_permanent: type: boolean description: >- Whether the permission is permanent or temporary. - `true`: Permanent authorization (no expiration) - `false`: Temporary authorization (expires at expiration_timestamp) example: false WhatsappInboundMessageLocation: type: object description: >- When you receive a notification of a user's static location, the location object provides the details of the location. properties: latitude: type: number format: double description: Latitude of location being sent. longitude: type: number format: double description: Longitude of location being sent. address: type: string description: Address of the location. name: type: string description: Name of the location. url: type: string description: >- URL for the website where the user downloaded the location information. WhatsappInboundMessageButton: type: object description: >- When the message type field is set to `button`, this object is included in the message object. properties: payload: type: string description: >- The payload for a button set up by the business that a customer clicked as part of an interactive message. text: type: string description: Button text. WhatsappMessageContact: type: object description: >- When the message type filed is set to `contacts`, this object is included in the message object. required: - name properties: addresses: type: array items: $ref: '#/components/schemas/WhatsappMessageContactAddress' birthday: type: string description: '`YYYY-MM-DD` formatted string.' example: '2022-09-27' emails: type: array items: $ref: '#/components/schemas/WhatsappMessageContactEmail' name: $ref: '#/components/schemas/WhatsappMessageContactName' org: $ref: '#/components/schemas/WhatsappMessageContactOrg' phones: type: array description: Contact phone number(s) formatted as a phone object. items: $ref: '#/components/schemas/WhatsappMessageContactPhone' urls: type: array description: Contact URL(s) formatted as a urls object. items: $ref: '#/components/schemas/WhatsappMessageContactUrl' vcard: type: string description: Optional vCard supplied with the shared contact payload. origin: type: string description: >- Set to `contact_request` when the user shared the contact in response to a request-contact-info message. example: contact_request WhatsappMessageReaction: type: object description: >- When a user reacts to messages with an emoji, the message type is set to `reaction`, and this field is included. required: - message_id properties: message_id: type: string description: >- Specifies the `wamid` of the message received that contained the reaction. example: wamid.BgNODYxN... emoji: type: string description: >- **Required** when you send a `reaction` message. Set it to `""` if you want to remove the emoji. **Optional** when you received a message from a user. This field is included when a user reacts to messages with an emoji. Otherwise, it indicates a user removed the emoji. WhatsappInboundMessageOrder: type: object description: >- When a customer places an order, the message type is set to `order`, and this field is included. properties: catalog_id: type: string description: The catalog ID. example: the-catalog_id product_items: type: array items: $ref: '#/components/schemas/WhatsappInboundMessageOrderProductItem' text: type: string description: Text message sent along with the order. WhatsappInboundMessageSystem: type: object description: >- When the message type is set to `system`, this field is included. This object is added to Webhooks if a user has changed their phone number and if a user’s identity has potentially changed on WhatsApp. properties: body: type: string description: >- Describes the system message event. Supported use cases are: - Phone number update: for when a user changes from an old number to a new number. - Identity update: for when a user identity has changed. wa_id: type: string description: |- **Added to Webhooks for phone number updates.** New WhatsApp ID of the customer. user_id: type: string description: |- **Added to Webhooks for phone number updates.** The customer's new WhatsApp Business-scoped user ID (BSUID). This field keeps Meta's original snake_case name inside the `system` object. example: US.13491208655302741919 parent_user_id: type: string description: >- **Added to Webhooks for phone number updates when parent BSUIDs are enabled.** The customer's new parent WhatsApp Business-scoped user ID. This field keeps Meta's original snake_case name inside the `system` object. example: US.ENT.11815799212886844831 type: type: string description: |- Supported types are: - `user_changed_number`: for a user changed number notification. - `user_identity_changed`: for user identity changed notification. user: type: string description: |- **Added to Webhooks for identity updates.** The new WhatsApp user ID of the customer. new_wa_id: type: string description: |- **Added to Webhooks for phone number updates.** New WhatsApp ID of the customer. WhatsappInboundMessageError: type: object description: When the message type `unsupported`, this object is included. properties: code: type: string description: The error code. example: 131051 title: type: string description: The error title. example: Message type unknown message: type: string description: The error message. example: Message type unknown error_data: type: object description: >- An error data object with the following properties: - `details`: A string describing the reason for the error. Example: `Message type is currently not supported.`. WhatsappInboundMessageContext: type: object description: Message context. properties: forwarded: type: boolean description: |- **Added to Webhooks if message was forwarded.** Set to `true` if the received message has been forwarded. frequently_forwarded: type: boolean description: >- **Added to Webhooks if message has been frequently forwarded.** Set to `true` if the received message has been forwarded more than five times. from: type: string description: >- **Added to Webhooks if message is an inbound reply to a sent message.** The WhatsApp ID (a phone number without the '+' prefix) of the sender of the sent message. id: type: string description: >- **Optional.** The `wamid` for the sent message for an inbound reply. `wamid` is the original message ID on WhatsApp’s platform. example: wamid.BgNODYxN... referred_product: $ref: '#/components/schemas/WhatsappInboundMessageReferredProduct' description: >- **Required for Product Inquiry Messages.** Specifies the product the user is requesting information about. See also [Sell Products & Services](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/sell-products-and-services). WhatsappInboundMessageReferral: type: object description: >- When a user messages businesses using call-to-actions buttons on [Ads that Click to WhatsApp](https://www.facebook.com/business/help/447934475640650) or a [Facebook Page call-to-action buttons](https://www.facebook.com/help/977869848936797), this field is included as an attachment. properties: source_url: type: string description: >- Specifies the URL that leads to the ad or post clicked by the user. Opening this URL takes you to the ad viewed by your user. source_type: type: string description: >- Specifies the type of the ad's source. Supported values are "ad" or "post". source_id: type: string description: Specifies the Meta ID for an ad or post. headline: type: string description: >- Specifies the headline used in the ad or post that generated the message. body: type: string description: >- The description, or body, from the ad or post that generated the message. media_type: type: string description: >- Media present in the ad or post the user clicked. Supported values are "image" or "video". image_url: type: string description: |- **Added if media_type is "image".** Contains a URL to the raw image. video_url: type: string description: |- **Added if media_type is "video".** Contains a URL to the video. thumbnail_url: type: string description: |- **Added if media_type is "video".** Contains a URL to the thumbnail image of the clicked video. ctwa_clid: type: string description: Click ID generated by Meta for ads that click to WhatsApp. WhatsappGroupWebhookField: type: string description: WhatsApp webhook field that produced the group event. enum: - group_lifecycle_update - group_participants_update - group_settings_update - group_status_update - messages WhatsappGroupWebhookType: type: string description: Specific WhatsApp group event type. enum: - group_create - group_delete - group_participants_add - group_participants_remove - group_join_request_created - group_join_request_revoked - group_settings_update - group_suspend - group_suspend_cleared - message_status WhatsappGroupWebhookStatus: type: string description: WhatsApp group webhook status. enum: - created - failed - deleted - added - removed - left - requested - revoked - updated - suspended - suspend_cleared - sent - delivered - read - expired WhatsappGroupCustomerProfile: type: object description: WhatsApp customer profile information. properties: name: type: string description: WhatsApp profile name. example: John Doe username: type: string description: WhatsApp username. example: john_doe WhatsappGroupJoinApprovalMode: type: string description: |- WhatsApp group join approval mode. - `approval_required`: New members must be approved before joining. - `auto_approve`: New members can join without approval. enum: - approval_required - auto_approve example: auto_approve WhatsappGroupWebhookParticipant: type: object description: Participant information included in group webhook payloads. properties: input: type: string description: The original participant input. example: US.1234 waId: type: string description: WhatsApp user ID. example: '16315551111' recipientUserId: type: string description: Business-scoped user ID. example: US.1234 parentRecipientUserId: type: string description: Parent business-scoped user ID. example: US.parent123 customerProfile: $ref: '#/components/schemas/WhatsappGroupCustomerProfile' errors: type: array description: Errors returned by WhatsApp for this participant. items: type: object additionalProperties: true WhatsappGroupWebhookSetting: type: object description: Group setting update detail. properties: name: type: string description: Setting name. enum: - profile_picture - group_subject - group_description example: group_subject text: type: string description: Text value for subject or description updates. example: New Purchase Inquiry updateSuccessful: type: boolean description: Whether the setting update succeeded. example: true mimeType: type: string description: MIME type for profile picture updates. example: image/jpeg sha256: type: string description: SHA-256 hash for profile picture updates. example: 2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae errors: type: array description: Errors returned by WhatsApp for this setting. items: type: object additionalProperties: true WhatsappGroupWebhookStatusContact: type: object description: Contact information included in group message status webhooks. properties: customerProfile: $ref: '#/components/schemas/WhatsappGroupCustomerProfile' waId: type: string description: WhatsApp user ID. example: '16315551111' recipientUserId: type: string description: Business-scoped user ID. example: US.1234 parentRecipientUserId: type: string description: Parent business-scoped user ID. example: US.parent123 WhatsappGroupWebhookMessageStatus: type: object description: Group message status detail. properties: id: type: string description: WhatsApp message ID. example: wamid.1 status: type: string description: Message status. enum: - sent - delivered - read - failed - expired example: delivered timestamp: type: integer format: int64 description: Unix timestamp indicating when the message status was updated. example: 1739321024 recipientId: type: string description: Recipient group ID. example: 120363345678901234@g.us recipientType: type: string description: Recipient type. enum: - group example: group recipientParticipantId: type: string description: WhatsApp user ID of the recipient participant. example: '16315551111' recipientUserId: type: string description: Business-scoped user ID of the recipient participant. example: US.1234 parentRecipientUserId: type: string description: Parent business-scoped user ID of the recipient participant. example: US.parent123 conversation: $ref: '#/components/schemas/WhatsappGroupWebhookConversation' pricing: $ref: '#/components/schemas/WhatsappGroupWebhookPricing' errors: type: array description: Errors returned by WhatsApp. items: type: object additionalProperties: true WhatsappBusinessUsernameStatus: type: string description: >- Business Username state for a WhatsApp business phone number. - `not_set`: No active or pending Business Username exists. - `active`: A Business Username is active. - `reserved`: A requested Business Username is reserved by Meta and may still be under review. - `pending_review`: Legacy compatibility value for an under-review request. New writes use `reserved`. If an active username exists while a new request is reserved or under review, `businessUsernameStatus` is `reserved`, `businessUsername` contains the still-active username, and `requestedBusinessUsername` contains the requested username. enum: - not_set - active - pending_review - reserved WhatsappPhoneNumberQualityRating: type: string description: >- Quality rating. One of `GREEN`, `YELLOW`, `RED`, or `UNKNOWN`. See also [Phone Number Quality Rating](https://www.facebook.com/business/help/896873687365001). - `GREEN`: High quality. - `YELLOW`: Medium quality. - `RED`: Low quality. - `UNKNOWN`: Unknown quality. enum: - GREEN - YELLOW - RED - UNKNOWN WhatsappPhoneNumberCodeVerificationStatus: type: string description: To see if a phone number has been verified via OTP (one-time password). enum: - VERIFIED - NOT_VERIFIED - EXPIRED WhatsappPhoneNumberStatus: type: string description: >- The status of a WhatsApp business phone number. - `PENDING`: Pending. Phone number is newly added. Verify and register this phone number so it can be connected to your account. - `UNVERIFIED`: Unverified. Verify this phone number to start sending messages. - `MANUAL_REVIEW`: Being reviewed. Phone number is currently being reviewed for connection to your account. - `DISCONNECTED`: Offline. Phone number is currently not reachable by WhatsApp servers. - `CONNECTED`: Connected. Phone number is associated with this account and working properly. - `FLAGGED`: Flagged. This phone number has been flagged due to low quality messages. - `WARNED`: Warned. A warning has been issued for this number, potentially due to spam reports. - `RATE_LIMITED`: Rate limited. The number of messages you can send from this phone number may be restricted. - `BANNED`: Banned. Phone number cannot be used with a WhatsApp account. - `RESTRICTED`: Restricted. This phone number has reached its 24-hour messaging limit and can no longer send messages to customers. Please wait until the messaging limit is reset to send messages. - `BLOCKED`: Message limit reached. The limit has been reached for this 24-hour period. - `MIGRATED`: Transferred. This phone number has been transferred to another WhatsApp Business account. - `UNKNOWN`: Unavailable. The status of this phone number can't be determined right now. enum: - PENDING - UNVERIFIED - MANUAL_REVIEW - DISCONNECTED - CONNECTED - FLAGGED - WARNED - RATE_LIMITED - BANNED - RESTRICTED - BLOCKED - MIGRATED - UNKNOWN WhatsappPhoneNumberNameStatus: type: string description: >- The review status of the current display name request. See also [Get Display Name Status](https://developers.facebook.com/docs/whatsapp/business-management-api/manage-phone-numbers#get-display-name-status--beta-). - `APPROVED`: The name has been approved. You can download your certificate now. - `AVAILABLE_WITHOUT_REVIEW`: The certificate for the phone is available and display name is ready to use without review. - `DECLINED`: The name has not been approved. You cannot download your certificate. - `EXPIRED`: Your certificate has expire and can no longer be downloaded. - `PENDING_REVIEW`: Your name request is under review. You cannot download your certificate. - `NONE`: No certificate is available. enum: - APPROVED - AVAILABLE_WITHOUT_REVIEW - DECLINED - EXPIRED - PENDING_REVIEW - NONE WhatsappPhoneNumberQualityUpdateEventEnum: type: string description: >- Indicates the update event type of WhatsApp phone number quality when a notification is sent to you. - `ONBOARDING`: Typically when the messaging limit changes from `TIER_NOT_SET` to another tier. - `UPGRADE`: Messaging limit tier upgraded. - `DOWNGRADE`: Messaging limit tier downgraded. - `FLAGGED`: Flagged status occurs when the quality rating reaches a low state. If the message quality improves to a high or medium state and maintains this for 7 days, your status will return to Connected. If the quality rating doesn't improve, your status will still return to Connected, but you'll be placed in a lower messaging limit tier. Learn more on [Phone Number Quality Rating](https://www.facebook.com/business/help/896873687365001) docs. - `UNFLAGGED`: Phone number status changes from `FLAGGED` to `CONNECTED`. enum: - ONBOARDING - UPGRADE - DOWNGRADE - FLAGGED - UNFLAGGED WhatsappPaymentStatus: type: string description: >- Status of this payment. - `captured`: Indicates the payment is successfully completed. - `pending`: Indicates the user attempted but yet to receive success transactions signal. enum: - captured - pending WhatsappPaymentTransaction: type: object description: Represents a transaction attempt for a payment. required: - id - type - status - createdTimestamp - updatedTimestamp - amount - currency properties: id: type: string description: Transaction ID. type: type: string description: >- The payment type for this transactions. One of `billdesk`, `razorpay`, `payu`, or `zaakpay`. enum: - billdesk - razorpay - payu - zaakpay status: type: string description: >- The status of the transaction. One of `pending`, `success` or `failed`. enum: - pending - success - failed createdTimestamp: type: integer format: int64 description: Time when transaction was created in epoch milliseconds. updatedTimestamp: type: integer format: int64 description: Time when transaction was last updated in epoch milliseconds. amount: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: Total amount that user has paid. currency: type: string description: |- The currency for this payment. Currently the only supported value is `INR`. methodType: type: string description: >- Describes the type of payment method used by consumer to pay for the order. Can be one of `upi`, `card`, `wallet`, or `netbanking`. The payment method information might not be available for failed payments. example: upi error: type: object description: >- The payment error details might not be available for all payments attempts. required: - code - reason properties: code: type: string description: >- Describes the payment failure reason that generated by payment gateway and Meta transmits this to partners. reason: type: string description: >- Describes the payment failure reason in plain text that is generated by payment gateway and Meta transmits this to partners. WhatsappTemplateCategory: type: string description: >- Category of WhatsApp templates. - `AUTHENTICATION`: Enable businesses to authenticate users with one-time passcodes, potentially at multiple steps in the login process (e.g., account verification, account recovery, integrity challenges). - `MARKETING`: Include promotions or offers, informational updates, or invitations for customers to respond / take action. Any conversation that does not qualify as utility or authentication is a marketing conversation. - `UTILITY`: Facilitate a specific, agreed-upon request or transaction or update to a customer about an ongoing transaction, including post-purchase notifications and recurring billing statements. enum: - AUTHENTICATION - MARKETING - UTILITY WhatsappTemplateSubCategory: type: string description: >- Subcategory of WhatsApp templates. - ORDER_STATUS: Order status template is categorized as `UTILITY` template and apart from name and language of choice, it has general template components such as `BODY`, `FOOTER` and additionally subcategory as `ORDER_STATUS`. enum: - ORDER_STATUS WhatsappTemplateComponent: type: object properties: type: type: string description: >- **Required.** Template component type. - `BODY`: Body components are text-only components and are required by all templates. Templates are limited to one body component. - `HEADER`: Headers are optional components that appear at the top of template messages. Headers support text, media (images, gif, videos, documents). Templates are limited to one header component. - `FOOTER`: Footers are optional text-only components that appear immediately after the body component. Templates are limited to one footer component. - `BUTTONS`: Buttons are optional interactive components that perform specific actions when tapped. - `LIMITED_TIME_OFFER`: Use for limited-time offer templates. The delivered message can display an offer expiration details section with a heading, an optional expiration timer, and the offer code itself. - `CAROUSEL`: Carousel templates allow you to send a single text message (1), accompanied by a set of up to 10 carousel cards (2) in a horizontally scrollable view. enum: - BODY - HEADER - FOOTER - BUTTONS - LIMITED_TIME_OFFER - CAROUSEL format: type: string description: '**Required for type `HEADER`.**' enum: - TEXT - IMAGE - GIF - VIDEO - DOCUMENT - LOCATION text: type: string description: >- For body text (type = `BODY`), maximum 1024 characters. For header text (type = `HEADER`, format = `TEXT`), maximum 60 characters. For footer text (type = `FOOTER`), maximum 60 characters. For card body text (`CAROUSEL` card component type = `BODY`), maximum 160 characters. maxLength: 1024 buttons: type: array description: >- **Required for type `BUTTONS`.** Buttons are optional interactive components that perform specific actions when tapped. Templates can have a mixture of up to 10 button components total, although there are limits to individual buttons of the same type as well as combination limits. If a template has more than three buttons, two buttons will appear in the delivered message and the remaining buttons will be replaced with a **See all options** button. Tapping the **See all options** button reveals the remaining buttons. maxItems: 10 items: $ref: '#/components/schemas/WhatsappTemplateComponentButton' add_security_recommendation: type: boolean description: >- **Optional. Only applicable in the `BODY` component of an AUTHENTICATION template.** Set to `true` if you want the template to include the string, *For your security, do not share this code.* Set to `false` to exclude the string. code_expiration_minutes: type: integer format: int32 description: >- **Optional. Only applicable in the `FOOTER` component of an AUTHENTICATION template.** Indicates number of minutes the password or code is valid. If omitted, the code expiration warning will not be displayed in the delivered message. Minimum 1, maximum 90. maximum: 90 minimum: 1 example: 5 limited_time_offer: $ref: '#/components/schemas/WhatsappTemplateComponentLimitedTimeOffer' example: $ref: '#/components/schemas/WhatsappTemplateComponentExample' cards: type: array description: |- **Required for type `CAROUSEL`.** Carousel templates support up to 10 carousel cards. maxItems: 10 items: $ref: '#/components/schemas/WhatsappTemplateComponentCard' WhatsappTemplateStatus: type: string description: >- The status of a WhatsApp template. - `PENDING`: The template is still under review. Review can take up to 24 hours. - `REJECTED`: The template has been rejected during review process. - `APPROVED`: The template is approved, and you may begin sending it to customers. - `PAUSED`: The template has been paused due to recurring negative feedback from customers. Message templates with this status cannot be sent to customers. See [Template Pausing](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#template-pausing). - `DISABLED`: The template has been disabled due to recurring negative feedback from customers or for violating one or more of our policies. Message templates with this status cannot be sent to customers. You may be able to edit a disabled message template and request an appeal. See [Appeals](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#appeals). - `ARCHIVED`: The template has been archived. Archived templates cannot be sent or edited. - `IN_APPEAL`: The template is in appeal. See also [Template Appeals](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#appeals). - `DELETED`: The template is deleted. enum: - PENDING - REJECTED - APPROVED - PAUSED - DISABLED - ARCHIVED - IN_APPEAL - DELETED example: REJECTED WhatsappTemplateQualityRating: type: string description: >- Quality rating of WhatsApp template. One of `GREEN`, `YELLOW`, `RED`, or `UNKNOWN`. See also [Template Quality Rating](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/#quality-rating). - `GREEN`: High quality. - `YELLOW`: Medium quality. - `RED`: Low quality. - `UNKNOWN`: Unknown quality. enum: - GREEN - YELLOW - RED - UNKNOWN WhatsappTemplateStatusUpdateEventEnum: type: string description: >- Used when an event happened on WhatsApp template status updates. - `PENDING`: Pending. - `APPROVED`: Approved. - `REJECTED`: Rejected. - `IN_APPEAL`: In appeal. See also [Template Appeals](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#appeals). - `PAUSED`: Paused. See also [Template Pausing](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#template-pausing). - `FLAGGED`: Flagged. The template is scheduled for disabling. - `DISABLED`: Disabled. See also [Template Pausing](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines#template-pausing). - `ARCHIVED`: Archived. The template status is updated to `ARCHIVED`. - `UNARCHIVED`: Unarchived. The template status is restored to the current status returned by Meta. If the status is `APPROVED`, this event still does not represent a new approval review. - `REINSTATED`: Reinstated. - `PENDING_DELETION`: Pending deletion. enum: - PENDING - APPROVED - REJECTED - IN_APPEAL - PAUSED - FLAGGED - DISABLED - ARCHIVED - UNARCHIVED - REINSTATED - PENDING_DELETION WhatsappApiError: type: object description: >- The original error object returned by WhatsApp. See [Handling Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling), [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes). required: - message - code properties: message: type: string description: A human-readable description of the error. example: HSM Template creation failed code: type: string description: An error code. example: 200002 type: type: string description: Error type. example: OAuthException error_subcode: type: string description: Additional code about the error. example: 2388109 error_user_msg: type: string description: >- The message to display to the user. The language of the message is based on the locale of the API request. example: This message template cannot be created. error_user_title: type: string description: >- The title of the dialog, if shown. The language of the message is based on the locale of the API request. example: Message Cannot Be Submitted fbtrace_id: type: string description: >- Internal support identifier. When reporting a bug related to a Graph API call, include the fbtrace_id to help us find log data for debugging. example: AVGjJ7ia2zJkrHG error_data: description: >- Additional data about the error. A string or map. - For template APIs, this field is a string describing the reason for the error. - For message APIs, this field is a map with property `details` describing the reason for the error. oneOf: - type: string - type: object additionalProperties: true WhatsappMessageText: type: object description: WhatsApp Message Text Object. required: - body properties: body: type: string description: >- Required for text messages. The text of the text message which can contain URLs which begin with http:// or https:// and formatting. See available formatting options here. If you include URLs in your text and want to include a preview box in text messages (preview_url: true), make sure the URL starts with http:// or https:// — https:// URLs are preferred. You must include a hostname, since IP addresses will not be matched. Maximum length: 4096 characters. maxLength: 4096 preview_url: type: boolean description: >- By default, WhatsApp recognizes URLs and makes them clickable, but you can also include a preview box with more information about the link. Set this field to true if you want to include a URL preview box. The majority of the time, the receiver will see a URL they can click on when you send an URL, set preview_url to true, and provide a body object with a http or https link. URL previews are only rendered after one of the following has happened: - The business has sent a message template to the user. - The user initiates a conversation with a "click to chat" link. - The user adds the business phone number to their address book and initiates a conversation. Default: `false`. WhatsappEchoMessageMedia: type: object description: Media metadata copied from a Meta Business Agent echo callback. properties: id: type: string description: Provider media ID, when supplied by the callback. link: type: string description: Provider media URL, when supplied by the callback. caption: type: string description: Media caption, when supplied by the callback. filename: type: string description: Original filename, when supplied by the callback. mime_type: type: string description: Provider MIME type copied from the callback. example: image/jpeg WhatsappMessageLocation: type: object description: Use for `location` messages. required: - latitude - longitude properties: latitude: type: number format: double description: Latitude of the location. longitude: type: number format: double description: Longitude of the location. name: type: string description: Name of the location. address: type: string description: Address of the location. Only displayed if `name` is present. WhatsappMessageInteractive: type: object description: Use for `interactive` messages. properties: type: type: string description: |- **Required.** The type of interactive message you want to send. - `button`: Use for Reply Buttons. - `list`: Use for List Messages. - `cta_url`: Use for Call-To-Action (CTA) URL Button Messages. - `product`: Use for Single Product Messages. - `product_list`: Use for Multi-Product Messages. - `catalog_message`: Use for Catalog Messages. - `location_request_message`: Use for Location Request Messages. - `order_details`: Use for Order Details Messages. - `order_status`: Use for Order Status Messages. - `voice_call`: Use for Voice Call Messages. - `flow`: Use for Flow Messages. enum: - button - list - cta_url - product - product_list - catalog_message - location_request_message - order_details - order_status - voice_call - flow action: $ref: '#/components/schemas/WhatsappMessageInteractiveAction' body: $ref: '#/components/schemas/WhatsappMessageInteractiveBody' header: $ref: '#/components/schemas/WhatsappMessageInteractiveHeader' footer: $ref: '#/components/schemas/WhatsappMessageInteractiveFooter' WhatsappMessageContext: type: object description: >- Used to mention a specific message you are replying to. The reply can be any message type. properties: message_id: type: string description: >- Specifies the `wamid` of the message your are replying to. `wamid` is the original message ID on WhatsApp’s platform. example: wamid.BgNODYxN... WhatsappMessageStatus: type: string description: >- 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. enum: - accepted - failed - sent - delivered - read WhatsappConversation: type: object description: >- WhatsApp defines a conversation as a 24-hour session of messaging between a person and a business. See also [Conversation-Based Pricing](https://developers.facebook.com/docs/whatsapp/pricing). properties: id: type: string description: Unique ID for the object. type: $ref: '#/components/schemas/WhatsappConversationType' originType: $ref: '#/components/schemas/WhatsappConversationOriginType' expireTime: type: string format: date-time description: >- Date when the conversation expires, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. example: '2022-06-01T12:00:00.000Z' WhatsappMessageType: type: string description: >- WhatsApp outbound message type. See also [WhatsApp messages](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages). enum: - template - text - image - audio - video - document - sticker - location - interactive - contacts - reaction WhatsappMessageTemplate: type: object description: Use for sending a WhatsApp `template` message. required: - name - language properties: name: type: string description: Name of the template. example: sample_whatsapp_template language: type: object description: >- Contains a language object. Specifies the language the template may be rendered in. properties: code: type: string description: >- The code of the language or locale to use. Accepts both language and language_locale formats (e.g., en and en_US). See [Supported Languages](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/supported-languages) for all codes. example: en_US policy: type: string description: >- The language policy the message should follow. Default (and only supported option): `deterministic`, which means that WhatsApp delivers the message template in exactly the language and locale asked for. example: deterministic required: - code components: type: array description: >- **Required when the specified template contains variables or media.** Array of component objects containing the parameters of the message. items: $ref: '#/components/schemas/WhatsappMessageTemplateComponent' WhatsappMessageMedia: type: object description: >- Use for `image`, `gif`, `video`, `audio`, `document`, or `sticker` messages. See also [Supported Media Types](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types). properties: id: type: string description: >- **Use this when media is uploaded to WhatsApp servers.** Provide the media object ID obtained from WhatsApp media upload API (https://docs.ycloud.com/reference/whatsapp_media-upload#/). Note: Either `id` or `link` must be provided. If both are provided, `id` takes precedence. link: type: string description: >- **Use this when sending media directly from your server.** The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. Note: WhatsApp Cloud API caches media resources for 10 minutes. To ensure latest content, add random query strings to the URL. Note: Either `id` or `link` must be provided. If both are provided, `id` takes precedence and `link` will be ignored. caption: type: string description: >- Describes the specified `image`, `gif`, `video`, or `document` media. Not applicable in the `header` of `template` or `interactive` messages. filename: type: string description: >- Describes the filename for the specific document. Use only with `document` media. WhatsappPricingCategory: type: string description: >- WhatsApp pricing category. - `referral_conversion`: Indicates a [free entry point conversation](https://developers.facebook.com/docs/whatsapp/pricing#free-entry-point-conversations). - `authentication`: Indicates the conversation was billed at authentication rate. - `authentication_international`: Indicates the conversation was conversation was billed at the [authentication-international rate](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates). - `marketing`: Indicates the conversation was billed at authentication rate. - `marketing_lite`: Indicates the conversation was billed at marketing-lite rate. - `utility`: Indicates the conversation was billed at utility rate. - `service`: Indicates the conversation was billed at service rate. See also [Conversation-Based Pricing](https://developers.facebook.com/docs/whatsapp/pricing). enum: - referral_conversion - authentication - authentication_international - marketing - marketing_lite - utility - service WhatsappPricingModel: type: string description: |- WhatsApp pricing model. - `PMP`: Per-message pricing applies. - `CBP`: Conversation-based pricing applies. enum: - PMP - CBP WhatsappPricingType: type: string description: >- WhatsApp pricing type. 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. enum: - regular - free_customer_service - free_entry_point AttributeChangeAction: type: object description: |- Represents a single change action performed on an attribute. For tag attributes, includes additional id and value fields. required: - action properties: action: type: string description: The type of change action performed. enum: - ADDED - REMOVED - CHANGED example: ADDED id: type: string description: |- The ID of the item when the attribute is 'tags'. This field is only present for tag-related changes. example: 686dd294334be8606a5bf312 value: type: string description: |- The value of the item when the attribute is 'tags'. This field is only present for tag-related changes. example: fsadf WhatsappMessageContactAddress: type: object description: Full contact address(es) formatted as an addresses object. properties: street: type: string description: Street number and name. city: type: string description: City name. state: type: string description: State abbreviation. zip: type: string description: ZIP code. country: type: string description: Full country name. country_code: type: string description: Two-letter country abbreviation. type: type: string description: Standard values are `HOME` and `WORK`. example: WORK WhatsappMessageContactEmail: type: object description: Contact email address(es) formatted as an emails object. properties: email: type: string description: Email address. type: type: string description: Standard values are `HOME` and `WORK`. example: WORK WhatsappMessageContactName: type: object description: Full contact name formatted as a name object. required: - formatted_name properties: formatted_name: type: string description: Full name, as it normally appears. first_name: type: string description: First name. last_name: type: string description: Last name. middle_name: type: string description: Middle name. suffix: type: string description: Name suffix. prefix: type: string description: Name prefix. WhatsappMessageContactOrg: type: object description: Contact organization information formatted as an org object. properties: company: type: string description: Name of the contact's company. department: type: string description: Name of the contact's department. title: type: string description: Contact's business title. WhatsappMessageContactPhone: type: object properties: phone: type: string description: >- Automatically populated with the `wa_id` value as a formatted phone number. type: type: string description: Standard Values are `CELL`, `MAIN`, `IPHONE`, `HOME`, and `WORK`. wa_id: type: string description: WhatsApp ID. WhatsappMessageContactUrl: type: object properties: url: type: string description: URL. type: type: string description: Standard values are `HOME` and `WORK`. WhatsappInboundMessageOrderProductItem: type: object properties: product_retailer_id: type: string description: The product SKU identifier. quantity: type: integer format: int32 description: Number of item. item_price: type: number format: double description: Unitary price of item. currency: type: string description: >- Price currency. [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217). example: USD WhatsappInboundMessageReferredProduct: type: object description: >- A Product Inquiry Message is received when a user is asking for more information about a specific product. These can be received as in two scenarios: 1. When a customer replies to Single or Multi-Product Messages. 2. When a customer accesses a business’ catalog through another entry point, navigates to a Product Details Page, and clicks Message Business about this Product. properties: catalog_id: type: string description: The catalog ID. product_retailer_id: type: string description: The product SKU identifier. WhatsappGroupWebhookConversation: type: object description: WhatsApp conversation object included in group message status webhooks. properties: id: type: string description: Conversation ID. example: conversation-id expirationTimestamp: type: integer format: int64 description: Unix timestamp indicating when the conversation expires. example: 1739321024 origin: $ref: '#/components/schemas/WhatsappGroupWebhookConversationOrigin' WhatsappGroupWebhookPricing: type: object description: Pricing information included in group message status webhooks. properties: billable: type: boolean description: Whether the message is billable. example: true pricingModel: type: string description: Pricing model. example: PMP type: type: string description: Pricing type. example: regular category: type: string description: >- Raw group pricing category reported by Meta. YCloud does not expose the internal MM Lite mapping in this webhook field. enum: - group_marketing - group_utility - group_service example: group_service WhatsappMessageOrderAmount: type: object description: Represents the amount of an order. required: - offset - value properties: offset: type: integer format: int32 description: Must be `100` for `INR`. example: 100 value: type: integer format: int32 description: |- Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234. example: 1234 description: type: string description: |- Use only for `tax`, `shipping`, or `discount`. Description of the amount. Max character limit is 60 characters. maxLength: 60 discount_program_name: type: string description: >- Use only for `discount`. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters. maxLength: 60 WhatsappTemplateComponentButton: type: object required: - type properties: type: $ref: '#/components/schemas/WhatsappTemplateComponentButtonType' text: type: string description: >- **Required for button type `PHONE_NUMBER` or `URL`.** Button text. For `CODE_CODE` buttons, the text is a pre-set value and cannot be customized. For `OTP` buttons, if omitted, the text will default to a pre-set value localized to the template's language. For example, `Copy Code` for English (US). If your template is using a one-tap autofill button and you supply this value, the authentication template message will display a copy code button with this text if we are unable to validate your [handshake](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates/autofill-button-authentication-templates#handshake). Maximum 25 characters. maxLength: 25 url: type: string description: >- **Required for button type `URL`.** URL of website. There can be at most 1 variable at the end of the URL. Example: `https://www.luckyshrub.com/shop?promo={{1}}`. 2000 characters maximum. maxLength: 2000 phone_number: type: string description: >- **Required for button type `PHONE_NUMBER`.** Alphanumeric string. Business phone number to be (display phone number) called when the user taps the button. 20 characters maximum. maxLength: 20 example: 15550051310 otp_type: $ref: '#/components/schemas/WhatsappTemplateComponentButtonOtpType' description: >- **Required for button type `OTP`.** Indicates button OTP type. Set to `COPY_CODE` if you want the template to use a copy code button, `ONE_TAP` to have it use a one-tap autofill button, or `ZERO_TAP` to have no button at all. autofill_text: type: string description: |- **One-tap and zero-tap buttons only.** One-tap button text. Maximum 25 characters. maxLength: 25 example: Autofill package_name: type: string description: |- **One-tap and zero-tap buttons only.** Your Android app's package name. example: com.example.myapplication signature_hash: type: string description: >- **One-tap and zero-tap buttons only.** Your app signing key hash. See [App Signing Key Hash](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates/zero-tap-authentication-templates#app-signing-key-hash). example: K8a%2FAINcGX7 zero_tap_terms_accepted: type: boolean description: >- **Zero-tap buttons only.** Set to `true` to indicate that you understand that your use of zero-tap authentication is subject to the WhatsApp Business Terms of Service, and that it's your responsibility to ensure your customers expect that the code will be automatically filled in on their behalf when they choose to receive the zero-tap code through WhatsApp. If set to `false`, the template will not be created as you need to accept zero-tap terms before creating zero-tap enabled message templates. example: type: array description: Sample full URL for a `URL` button with a variable. items: type: string flow_id: type: string description: >- **Conditionally required for button type `FLOW`.** The unique ID of the Flow. Cannot be used if `flow_name` or `flow_json` parameters are provided. Only one of these parameters is allowed. example: '1' flow_name: type: string description: >- **Conditionally required for button type `FLOW`.** The name of the Flow. Cannot be used if `flow_id` or `flow_json` parameters are provided. Only one of these parameters is allowed. The Flow ID is stored in the message template, not the name, so changing the Flow name will not affect existing message templates. flow_json: type: string description: >- **Conditionally required for button type `FLOW`.** The Flow JSON encoded as string with escaping. The Flow JSON specifies the content of the Flow. Cannot be used if `flow_id` or `flow_name` parameters are provided. Only one of these parameters is allowed. flow_action: type: string description: |- **Use for button type `FLOW`.** Either `navigate` or `data_exchange`. Defaults to `navigate`. example: navigate navigate_screen: type: string description: |- **Required if `flow_action` is `navigate`.** The unique ID of the Screen in the Flow. example: WELCOME_SCREEN WhatsappTemplateComponentLimitedTimeOffer: type: object description: Use for `LIMITED_TIME_OFFER` components. properties: text: type: string description: |- **Required.** Offer details text. Maximum 16 characters. maxLength: 16 example: Expiring offer! has_expiration: type: boolean description: >- **Optional.** Set to `true` to have the [offer expiration details](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/limited-time-offer-templates#offer-expiration-details) appear in the delivered message. If set to `true`, the copy code button component must be included in the `buttons` array, and must appear first in the array. If set to `false`, offer expiration details will not appear in the delivered message and the copy code button component is optional. If including the copy code button, it must appear first in the `buttons` array. WhatsappTemplateComponentExample: type: object description: >- **Required** when: - `type` is `HEADER`, and `format` is one of `IMAGE`, `GIF`, `VIDEO`, or `DOCUMENT`. Provide a sample media URL in `header_url`. - `type` is `HEADER`, `format` is `TEXT`, and a variable is used in `text`. Provide a sample value for that variable in `header_text`. There can be at most 1 variable in `HEADER` text. - `type` is `BODY`, and variables are used in `text`. Provide sample values for those variables in `body_text`. properties: body_text: type: array description: Sample values for variables in `text` of a `BODY` component. items: type: array items: type: string header_text: type: array description: Sample value for the variable in `text` of a `HEADER` component. items: type: string header_url: type: array description: >- Sample media URL for a `HEADER` component whose format is one of `IMAGE`, `GIF`, `VIDEO`, or `DOCUMENT`. Supported types: - For `IMAGE`, the URL must end with one of `.jpg`, `.jpeg`, or `.png`, size limit is 5MB. - For `GIF`, the URL must end with `.mp4`, size limit is 3.5MB. - For `VIDEO`, the URL must end with `.mp4`, size limit is 16MB. - For `DOCUMENT`, the URL must end with `.pdf`, size limit is 100MB. items: type: string WhatsappTemplateComponentCard: type: object description: >- Carousel templates support up to 10 carousel cards. Cards must have a media header (image or video) and can optionally include body text and up to 2 quick reply buttons, phone number buttons, or URL buttons (button types can be mixed). properties: components: type: array description: |- **Required.** Card components. items: $ref: '#/components/schemas/WhatsappTemplateComponentCardComponent' description: >- Cards must have a media header (image or video) and can optionally include body text and up to 2 quick reply buttons, phone number buttons, or URL buttons (button types can be mixed). WhatsappMessageInteractiveAction: type: object description: >- **Required.** Action you want the user to perform after reading the `interactive` message. properties: buttons: type: array description: Required for Reply Buttons. You can have up to 3 buttons. maxItems: 3 items: $ref: '#/components/schemas/WhatsappMessageInteractiveActionButton' button: type: string description: >- Required for List Messages. Button content. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters. maxLength: 20 catalog_id: type: string description: >- Required for Single Product Messages and Multi-Product Messages. Unique identifier of the Facebook catalog linked to your WhatsApp Business Account. This ID can be retrieved via the [Meta Commerce Manager](https://business.facebook.com/commerce). product_retailer_id: type: string description: |- Required for Single Product Messages and Multi-Product Messages. Unique identifier of the product in a catalog. sections: type: array description: |- Required for List Messages and Multi-Product Messages. Array of section objects. Minimum of 1, maximum of 10. minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/WhatsappMessageInteractiveActionSection' name: type: string description: |- Action name. Required for Call-To-Action (CTA) buttons. - `cta_url`: Use for Call-To-Action (CTA) URL buttons. - `catalog_message`: Use for Catalog Messages. - `send_location`: Use for Location Request buttons. - `flow`: Use for Flow buttons. - `review_and_pay`: Use for Order Details buttons. - `review_order`: Use for Order Status buttons. - `voice_call`: Use for Voice Call buttons. enum: - cta_url - catalog_message - send_location - flow - review_and_pay - review_order - voice_call parameters: $ref: '#/components/schemas/WhatsappMessageInteractiveActionParameters' WhatsappMessageInteractiveBody: type: object description: Optional for type `product`. Required for other message types. properties: text: type: string description: >- The body content of the message. Emojis and markdown are supported. Maximum length: 1024 characters. maxLength: 1024 WhatsappMessageInteractiveHeader: type: object description: Required for type `product_list`. Optional for other types. properties: type: type: string description: >- **Required.** The header type you would like to use. - `text`: Used for List Messages, Reply Buttons, and Multi-Product Messages. - `video`: Used for Reply Buttons. - `image`: Used for Reply Buttons. - `document`: Used for Reply Buttons. enum: - text - image - video - document text: type: string description: Text for the header. Formatting allows emojis, but not markdown. maxLength: 60 image: $ref: '#/components/schemas/WhatsappMessageMedia' video: $ref: '#/components/schemas/WhatsappMessageMedia' document: $ref: '#/components/schemas/WhatsappMessageMedia' WhatsappMessageInteractiveFooter: type: object description: Optional. An object with the footer of the message. properties: text: type: string description: >- The footer content. Emojis and markdown are supported. Links are supported. Maximum length: 60 characters. maxLength: 60 WhatsappConversationType: type: string description: >- Conversation type. There is a charge when the first business message of this conversation is delivered, initiating the 24-hour conversation session. As such, the conversation type can be `null` before the first message is delivered. - `FREE_ENTRY`: Conversations originating from a [free entry point](https://developers.facebook.com/docs/whatsapp/pricing#free-entry-point-conversations). - `FREE_TIER`: Conversations within the monthly [free tier](https://developers.facebook.com/docs/whatsapp/pricing#free-tier-conversations). - `REGULAR`: Any conversations that did not originate from a [free entry point](https://developers.facebook.com/docs/whatsapp/pricing#free-entry-point-conversations) or are above the monthly [free tier](https://developers.facebook.com/docs/whatsapp/pricing#free-tier-conversations) allotment. enum: - FREE_ENTRY - FREE_TIER - REGULAR WhatsappConversationOriginType: type: string description: >- Indicates [conversation category](https://developers.facebook.com/docs/whatsapp/pricing#conversation-categories). This can also be referred to as a conversation entry point. - `referral_conversion`: Indicates a [free entry point conversation](https://developers.facebook.com/docs/whatsapp/pricing#free-entry-point-conversations). - `authentication`: Indicates the conversation was opened by a business sending template categorized as `AUTHENTICATION` to the customer. This applies any time it has been more than 24 hours since the last customer message. - `marketing`: Indicates the conversation was opened by a business sending template categorized as `MARKETING` to the customer. This applies any time it has been more than 24 hours since the last customer message. - `utility`: Indicates the conversation was opened by a business sending template categorized as `UTILITY` to the customer. This applies any time it has been more than 24 hours since the last customer message. - `service`: Indicates that the conversation opened by a business replying to a customer within a [customer service window](https://developers.facebook.com/docs/whatsapp/pricing#customer-service-windows). enum: - referral_conversion - authentication - marketing - utility - service WhatsappMessageTemplateComponent: type: object description: Component object containing the parameters of the message. required: - type properties: type: type: string description: Component type. enum: - header - body - button - limited_time_offer - carousel - order_status sub_type: type: string description: >- **Required when type is `button`.** Type of button. - `quick_reply`: Refers to a previously created quick reply button that allows for the customer to return a predefined message. - `url`: Refers to a previously created url button that allows the customer to visit the URL generated by appending the text parameter to the predefined prefix URL in the template. - `copy_code`: Refers to a previously created copy code button that allows the customer to copy a text string (defined when the template is sent in a template message) to the device's clipboard when tapped by the app user. - `catalog`: Refers to a previously created catalog button that allows the customer to view your product catalog. - `mpm`: Refers to a previously created MPM (multi-product message) button that allows the customer to browser products and sections. - `flow`: Refers to a previously created flow button that allows the customer to interact with a [flow](https://developers.facebook.com/docs/whatsapp/flows). - `order_details`: Refers to a previously created order details button that allows the customer to view the details of an order. enum: - quick_reply - url - copy_code - catalog - mpm - flow - order_details index: type: integer format: int32 minimum: 0 maximum: 9 description: >- **Required when `type` = `button`. Not used for the other types.** Indicates order in which button should appear, if the template uses multiple buttons. Buttons are zero-indexed, so setting value to 0 will cause the button to appear first, and another button with an index of 1 will appear next, etc. parameters: type: array description: >- **Required when `type` = `button`, or there are variables in the corresponding template component, or the template `HEADER` format is media (`IMAGE`, `VIDEO`, or `DOCUMENT`).** Array of parameter objects with the content of the message. items: $ref: '#/components/schemas/WhatsappMessageTemplateComponentParameter' cards: type: array description: >- Use for `carousel` components. Provides card components containing the parameters of the message. items: $ref: '#/components/schemas/WhatsappMessageTemplateComponentCard' WhatsappGroupWebhookConversationOrigin: type: object properties: type: type: string description: Conversation origin type. example: service WhatsappTemplateComponentButtonType: type: string description: >- Button type. - `PHONE_NUMBER`: Phone number buttons call the specified business phone number when tapped by the app user. Templates are limited to one phone number button. - `URL`: URL buttons load the specified URL in the device's default web browser when tapped by the app user. Templates are limited to two URL buttons. - `QUICK_REPLY`: Quick reply buttons are custom text-only buttons that immediately message you with the specified text string when tapped by the app user. Templates are limited to 10 quick reply buttons. If using quick reply buttons with other buttons, buttons must be organized into two groups: quick reply buttons and non-quick reply buttons. - `COPY_CODE`: Copy code buttons copy a text string (defined when the template is sent in a template message) to the device's clipboard when tapped by the app user. Templates are limited to one copy code button. - `OTP`: One-time password (OTP) buttons are a special type of URL button component used with authentication templates. - `CATALOG`: When a customer taps the **View catalog** button in a catalog template message, your product catalog appears within WhatsApp. - `MPM`: Customers can browse products and sections by tapping the **View items** button in a multi-product template message. - `FLOW`: Use this type to specify the [Flow](https://developers.facebook.com/docs/whatsapp/flows) to be sent with the template message. - `ORDER_DETAILS`: Provides a order details button with `Review and Pay` text. - `VOICE_CALL`: Triggers a WhatsApp call, when clicked by a WhatsApp customer. enum: - PHONE_NUMBER - URL - QUICK_REPLY - COPY_CODE - OTP - CATALOG - MPM - FLOW - ORDER_DETAILS - VOICE_CALL WhatsappTemplateComponentButtonOtpType: type: string description: >- Indicates button OTP type. Set to `COPY_CODE` if you want the template to use a copy code button, `ONE_TAP` to have it use a one-tap autofill button, or `ZERO_TAP` to have no button at all. enum: - COPY_CODE - ONE_TAP - ZERO_TAP WhatsappTemplateComponentCardComponent: type: object properties: type: type: string description: >- **Required.** Card component type. - `BODY`: Body components are text-only components. Cards must have body text. - `HEADER`: Cards must have a media header (image or video). - `BUTTONS`: Buttons are interactive components that perform specific actions when tapped. Cards must have at least one button, up to 2 buttons. enum: - BODY - HEADER - BUTTONS format: type: string description: |- **Required for type `HEADER`.** Cards must have a media header (image or video). enum: - IMAGE - VIDEO text: type: string description: |- **Required for type `BODY`.** Card body text supports variables. Maximum 160 characters. maxLength: 160 buttons: type: array description: >- **Required for type `BUTTONS`.** Cards must have at least one button. Supports 2 buttons. Buttons can be the same or a mix of quick reply buttons, phone number buttons, or URL buttons. minItems: 1 maxItems: 2 items: $ref: '#/components/schemas/WhatsappTemplateComponentButton' example: $ref: '#/components/schemas/WhatsappTemplateComponentExample' WhatsappMessageInteractiveActionButton: type: object description: A button object in `interactive` messages. properties: type: type: string description: Only supported type is `reply` (for Reply Button). enum: - reply reply: type: object properties: title: type: string description: >- Button title. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters. maxLength: 20 id: type: string description: >- Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user. Maximum length: 256 characters. You cannot have leading or trailing spaces when setting the ID. maxLength: 256 WhatsappMessageInteractiveActionSection: type: object description: WhatsApp Message Interactive Section Object. properties: title: type: string description: |- **Required if the message has more than one section.** Title of the section. Maximum length: 24 characters. maxLength: 24 rows: type: array description: >- Contains a list of rows. You can have a total of 10 rows across your sections. Each row must have a title (Maximum length: 24 characters) and an ID (Maximum length: 200 characters). You can add a description (Maximum length: 72 characters), but it is optional. maxItems: 10 items: $ref: '#/components/schemas/WhatsappMessageInteractiveActionSectionRow' product_items: type: array description: >- Required for Multi-Product Messages. Array of product objects. There is a minimum of 1 product per section and a maximum of 30 products across all sections. minItems: 1 maxItems: 30 items: $ref: >- #/components/schemas/WhatsappMessageInteractiveActionSectionProductItem WhatsappMessageInteractiveActionParameters: type: object description: |- Action parameters. Required for Call-To-Action (CTA) buttons. properties: display_text: type: string description: |- Text of the CTA URL button. Maximum length: 20 bytes. maxLength: 20 example: See Docs url: type: string description: URL of the CTA URL button. example: https://developers.facebook.com/docs/whatsapp thumbnail_product_retailer_id: type: string description: >- Item SKU number. Labeled as **Content ID** in the [Commerce Manager](https://business.facebook.com/commerce). The thumbnail of this item will be used as the message's header image. flow_message_version: type: string description: |- Use for `flow` buttons. Value must be "3". flow_token: type: string description: >- Use for `flow` buttons. Flow token that is generated by the business to serve as an identifier. Defaults to `unused`. flow_id: type: string description: >- Conditionally required for `flow` buttons. Unique ID of the Flow provided by WhatsApp. Cannot be used with the `flow_name` parameter. flow_name: type: string description: >- Conditionally required for `flow` buttons. The name of the Flow that you created. Cannot be used with the `flow_id` parameter. Changing the Flow name will require updating this parameter to match the new name. flow_cta: type: string description: >- Required for `flow` buttons. Text on the CTA button. For example: "Open flow!". Maximum length: 20 characters. maxLength: 20 example: Open flow! flow_action: type: string description: |- Use for `flow` buttons. Either `navigate` or `data_exchange`. Defaults to `navigate`. example: navigate flow_action_payload: type: object description: >- Required if `flow_action` is `navigate`. Should be omitted otherwise. properties: screen: type: string description: >- The ID of the screen displayed first. It needs to be an **entry** screen. data: type: object description: >- Optional input data for the first screen of the Flow. If provided, this must be a non-empty object. additionalProperties: type: object reference_id: type: string description: >- Required for `review_and_pay` buttons. Unique identifier for the order provided by the business. It is case sensitive and cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters. The `reference_id` must be unique for each order_details message for a given business. If there is a need to send multiple order_details messages for the same order, it is recommended to include a sequence number in the reference_id (for example, "BM345A-12") to ensure reference_id uniqueness. type: type: string description: >- Required for `review_and_pay` buttons. The type of goods being paid for in this order. Current supported options are `digital-goods` and `physical-goods`. beneficiaries: type: array description: >- Required for `review_and_pay` buttons. An array of beneficiaries for this order. A beneficiary is an intended recipient for shipping the physical goods in the order. Beneficiary information isn't shown to users but is needed for legal and compliance reasons. items: $ref: '#/components/schemas/WhatsappMessageOrderBeneficiary' currency: type: string description: |- Required for `review_and_pay` buttons. The currency for this order. Currently the only supported value is `INR`. total_amount: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: |- Required for `review_and_pay` buttons. The total amount for this order. order: $ref: '#/components/schemas/WhatsappMessageOrderInfo' description: >- Required for `review_and_pay` or `review_order` buttons. For `review_and_pay` buttons, provides order `status`, `items`, `subtotal`, `tax`, etc. For `review_order` buttons, provides only order `status` and `description`. payment_settings: type: array description: |- Required for `review_and_pay` buttons. Payment settings for the order. items: $ref: '#/components/schemas/WhatsappMessageOrderPaymentSetting' WhatsappMessageTemplateComponentParameter: type: object properties: type: type: string description: >- **Required.** Component parameter type. - `text`: Used when the template component type is `BODY`, or the `HEADER` component format is `TEXT`. - `image`: Used when the template `HEADER` component is `IMAGE`. - `gif`: Used when the template `HEADER` component is `GIF`. - `video`: Used when the template `HEADER` component is `VIDEO`. - `document`: Used when the template `HEADER` component is `DOCUMENT`. - `payload`: Used when the template component button type is `QUICK_REPLY`. - `coupon_code`: Used when the template component button type is `COPY_CODE`. - `limited_time_offer`: Used when the template component type is `LIMITED_TIME_OFFER`. - `action`: Used when the template component button type is `CATALOG`, `MPM`, `FLOW`, or `ORDER_DETAILS`. - `order_status`: Used when the template subcategory is `ORDER_STATUS`. - `location`: Used when the template `HEADER` component is `LOCATION`. enum: - text - image - gif - video - document - payload - coupon_code - limited_time_offer - action - order_status - location text: type: string description: >- **Required when `type` = `text`.** The message's text. For the header component, the character limit is 60 characters. For the body component, the character limit is 1024 characters. For url buttons, it indicates the developer-provided suffix that is appended to the predefined prefix URL in the template. payload: type: string description: >- Required for `quick_reply` buttons. Developer-defined payload that is returned when the button is clicked in addition to the display text on the button. coupon_code: type: string description: |- **Required when `type` = `coupon_code`.** The coupon code to be copied when the customer taps the button. image: $ref: '#/components/schemas/WhatsappMessageMedia' description: '**Required when the template `HEADER` format is `IMAGE`.**' gif: $ref: '#/components/schemas/WhatsappMessageMedia' description: '**Required when the template `HEADER` format is `GIF`.**' video: $ref: '#/components/schemas/WhatsappMessageMedia' description: '**Required when the template `HEADER` format is `VIDEO`.**' document: $ref: '#/components/schemas/WhatsappMessageMedia' description: '**Required when the template `HEADER` format is `DOCUMENT`.**' limited_time_offer: $ref: >- #/components/schemas/WhatsappMessageTemplateComponentParameterLimitedTimeOffer action: $ref: '#/components/schemas/WhatsappMessageTemplateComponentParameterAction' order_status: $ref: '#/components/schemas/WhatsappMessageOrderStatus' location: $ref: '#/components/schemas/WhatsappMessageLocation' description: '**Required when `type` = `location`.**' WhatsappMessageTemplateComponentCard: type: object description: Card component containing the parameters of the message. properties: card_index: type: integer format: int32 description: >- **Required.** Zero-indexed order in which card appears within the card carousel. 0 indicates first card, 1 indicates second card, etc. minimum: 0 maximum: 9 components: type: array description: Card component. items: $ref: '#/components/schemas/WhatsappMessageTemplateComponentCardComponent' WhatsappMessageInteractiveActionSectionRow: type: object properties: id: type: string description: 'Unique row ID. Maximum length: 200 characters.' maxLength: 200 title: type: string description: 'Row title content. Maximum length: 24 characters.' maxLength: 24 description: type: string description: 'Row description content. Maximum length: 72 characters.' maxLength: 72 WhatsappMessageInteractiveActionSectionProductItem: type: object properties: product_retailer_id: type: string description: |- Required for Multi-Product Messages. Unique identifier of the product in a catalog. WhatsappMessageOrderBeneficiary: type: object description: >- A beneficiary is an intended recipient for shipping the physical goods in the order. Beneficiary information isn't shown to users but is needed for legal and compliance reasons. required: - name - address_line1 - city - state - country - postal_code properties: name: type: string description: >- Name of the individual or business receiving the physical goods. Cannot exceed 200 characters. maxLength: 200 address_line1: type: string description: >- Shipping address (Door/Tower Number, Street Name etc.). Cannot exceed 100 characters. maxLength: 100 address_line2: type: string description: >- Shipping address (Landmark, Area, etc.). Cannot exceed 100 characters. maxLength: 100 city: type: string description: Name of the city. state: type: string description: Name of the state. country: type: string description: |- Name of the country. Currently the only supported value is `India`. postal_code: type: string description: 6-digit zipcode of shipping address. minLength: 6 maxLength: 6 WhatsappMessageOrderInfo: type: object description: Order info. properties: status: $ref: '#/components/schemas/WhatsappMessageOrderStatusEnum' type: type: string description: >- Only supported value is `quick_pay`. When this field is passed in we hide the "Review and Pay" button and only show the "Pay Now" button in the order details bubble. catalog_id: type: string description: >- Unique identifier of the Facebook catalog being used by the business. If you do not provide this field, you must provide the following fields inside the items object: `country_of_origin`, `importer_name`, and `importer_address`. items: type: array description: Array of items in the order. items: $ref: '#/components/schemas/WhatsappMessageOrderItem' subtotal: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: >- The value **must be equal** to sum of `order.amount.value` * `order.amount.quantity`. tax: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: The tax information for this order. shipping: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: The shipping cost of the order. discount: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: The discount amount for this order. expiration: $ref: '#/components/schemas/WhatsappMessageOrderExpiration' description: type: string description: >- **Optional.** Text for sharing status related information. Could be useful while sending cancellation. Max character limit is 120 characters. maxLength: 120 WhatsappMessageOrderPaymentSetting: type: object description: Payment settings for the order. required: - type - payment_gateway properties: type: type: string description: Must be set to `payment_gateway`. example: payment_gateway payment_gateway: $ref: '#/components/schemas/WhatsappMessageOrderPaymentGateway' WhatsappMessageTemplateComponentParameterLimitedTimeOffer: type: object description: Required if template uses offer expiration details. properties: expiration_time_ms: type: integer format: int64 description: |- **Required.** Offer code expiration time as a UNIX timestamp in milliseconds. example: '1698562800000' WhatsappMessageTemplateComponentParameterAction: type: object description: >- Required if template uses catalog or MPM (multi-product message) buttons. properties: thumbnail_product_retailer_id: type: string description: >- **Optional.** Use for catalog and MPM template messages. Item SKU number. Labeled as Content ID in the Commerce Manager. The thumbnail of this item will be used as the message's header image. If the `parameters` object is omitted, the product image of the first item in your catalog will be used. example: 2lc20305pt sections: type: array description: |- Use for MPM templates. Product sections. You can define up to 10 sections. maxItems: 10 items: $ref: >- #/components/schemas/WhatsappMessageTemplateComponentParameterActionSection flow_token: type: string description: >- Use for `FLOW` buttons. Flow token that is generated by the business to serve as an identifier. Defaults to `unused`. flow_action_data: type: object additionalProperties: type: object description: |- Use for `FLOW` buttons. JSON object with the data payload for the first screen. order_details: $ref: '#/components/schemas/WhatsappMessageOrderDetails' description: Required for `order_details` buttons. WhatsappMessageOrderStatus: type: object properties: reference_id: type: string description: Unique identifier for the order provided by the business. order: $ref: '#/components/schemas/WhatsappMessageOrderInfo' description: >- Provides only `status` and `description` of this order for `order_status` messages. WhatsappMessageTemplateComponentCardComponent: type: object description: Card component object containing the parameters of the message. required: - type properties: type: type: string description: Component type. enum: - header - body - button sub_type: type: string description: >- **Required when type is `button`.** Type of button. - `quick_reply`: Refers to a previously created quick reply button that allows for the customer to return a predefined message. - `url`: Refers to a previously created url button that allows the customer to visit the URL generated by appending the text parameter to the predefined prefix URL in the template. enum: - quick_reply - url index: type: integer format: int32 minimum: 0 maximum: 9 description: >- **Required when `type` = `button`. Not used for the other types.** Indicates order in which button should appear, if the template uses multiple buttons. Buttons are zero-indexed, so setting value to 0 will cause the button to appear first, and another button with an index of 1 will appear next, etc. parameters: type: array description: >- **Required when `type` = `button`, or there are variables in the corresponding template component, or the card component `HEADER` format is media (`IMAGE`, `VIDEO`).** Array of parameter objects with the content of the message. items: $ref: '#/components/schemas/WhatsappMessageTemplateComponentParameter' WhatsappMessageOrderStatusEnum: type: string description: >- Only supported value in the `order_details` message is `pending`. In an `order_status` message, `status` can be: `pending`, `processing`, `partially_shipped`, `shipped`, `completed`, or `canceled`. enum: - pending - processing - partially_shipped - shipped - completed - canceled WhatsappMessageOrderItem: type: object required: - name - amount - quantity properties: retailer_id: type: string description: Content ID for an item in the order from your catalog. name: type: string description: >- The item's name to be displayed to the user. Cannot exceed 60 characters. maxLength: 60 image: $ref: '#/components/schemas/WhatsappMessageMedia' description: Custom image for the item to be displayed to the user. amount: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: The price per item. sale_amount: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: >- The discounted price per item. This should be less than the original amount. If included, this field is used to calculate the subtotal amount. quantity: type: integer format: int32 description: The number of items in the order. country_of_origin: type: string description: |- Required if `catalog_id` is not present. The country of origin of the product. importer_name: type: string description: |- Required if `catalog_id` is not present. Name of the importer company. importer_address: type: string description: |- Required if `catalog_id` is not present. Address of importer company. WhatsappMessageOrderExpiration: type: object description: Expiration for this order. required: - timestamp properties: timestamp: type: string description: >- A string of UTC timestamp in seconds of time when order should expire. Minimum threshold is 300 seconds. example: '1727438564' description: type: string description: Text explanation for expiration. maxLength: 120 WhatsappMessageOrderPaymentGateway: type: object description: An object that describes payment account information. required: - type - configuration_name properties: type: type: string description: >- Payment type. Must set this to `billdesk`, `razorpay`, `payu`, or `zaakpay`, if you have linked your BillDesk, Razorpay, PayU, or Zaakpay payment gateway to accept payments. enum: - billdesk - razorpay - payu - zaakpay configuration_name: type: string description: >- The name of the pre-configured payment configuration to use for this order and must not exceed 60 characters. This value must match with a payment configuration set up on the WhatsApp Business Manager. maxLength: 60 billdesk: $ref: >- #/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayBilldesk payu: $ref: >- #/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayPayu razorpay: $ref: >- #/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayRazorpay zaakpay: $ref: >- #/components/schemas/WhatsappMessageOrderPaymentSettingPaymentGatewayZaakpay WhatsappMessageTemplateComponentParameterActionSection: type: object properties: title: type: string description: |- Section title text. Maximum 24 characters. Markdown is not supported. maxLength: 24 product_items: type: array description: >- Array of product SKU numbers. There is a minimum of 1 product per section and a maximum of 30 products across all sections. minItems: 1 maxItems: 30 items: $ref: >- #/components/schemas/WhatsappMessageTemplateComponentParameterActionSectionProductItem WhatsappMessageOrderDetails: type: object description: >- Contains the order details when sending a template message with a `order_details` button. required: - currency - order - reference_id - total_amount - type - payment_settings properties: currency: type: string description: |- The currency for this order. Currently the only supported value is `INR`. order: $ref: '#/components/schemas/WhatsappMessageOrderInfo' description: Provides order `status`, `items`, `subtotal`, `tax`, etc. reference_id: type: string description: >- Unique identifier for the order provided by the business. It is case sensitive and cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters. The `reference_id` must be unique for each order_details message for a given business. If there is a need to send multiple order_details messages for the same order, it is recommended to include a sequence number in the reference_id (for example, "BM345A-12") to ensure reference_id uniqueness. total_amount: $ref: '#/components/schemas/WhatsappMessageOrderAmount' description: The total amount of the order. type: type: string description: >- The type of goods being paid for in this order. Current supported options are `digital-goods` and `physical-goods`. payment_settings: type: array description: Payment settings for the order. items: $ref: '#/components/schemas/WhatsappMessageOrderPaymentSetting' WhatsappMessageOrderPaymentSettingPaymentGatewayBilldesk: type: object description: >- Additional info for BillDesk. User-defined fields (extra) are used to store any information corresponding to a particular order. Each extra field has a maximum character limit of 120. properties: additional_info1: type: string additional_info2: type: string additional_info3: type: string additional_info4: type: string additional_info5: type: string additional_info6: type: string additional_info7: type: string WhatsappMessageOrderPaymentSettingPaymentGatewayPayu: type: object description: >- Additional info for PayU. User-defined fields (udf) are used to store any information corresponding to a particular order. Each UDF field has a maximum character limit of 255. properties: udf1: type: string udf2: type: string udf3: type: string udf4: type: string WhatsappMessageOrderPaymentSettingPaymentGatewayRazorpay: type: object description: Additional info for Razorpay. properties: receipt: type: string description: >- Receipt number that corresponds to this order, set for your internal reference. Maximum length of 40 characters supported with minimum length greater than 0 characters. notes: type: object additionalProperties: type: string description: >- The object can be key value pairs with maximum 15 keys and each value limits to 256 characters. WhatsappMessageOrderPaymentSettingPaymentGatewayZaakpay: type: object description: >- Additional info for Zaakpay. User-defined fields (extra) are used to store any information corresponding to a particular order. Each extra field has a maximum character limit of 180. properties: extra1: type: string extra2: type: string WhatsappMessageTemplateComponentParameterActionSectionProductItem: type: object properties: product_retailer_id: type: string description: >- SKU number of the item you want to appear in the section. SKU numbers are labeled as **Content ID** in the [Commerce Manager](https://business.facebook.com/commerce). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.