{"openapi":"3.0.1","info":{"title":"WhatsApp Channel API","description":"Provides methods for configuring and managing WhatsApp Cloud API channels\nwithin an API Space. Supports creating and retrieving WhatsApp\nconfigurations, registering and removing phone numbers, and retrieving\nWhatsApp message templates from a given WhatsApp Business Account.","version":"1.0.1"},"servers":[{"url":"https://{region}-api.dotdigital.com","variables":{"region":{"description":"The Dotdigital region id your account belongs to","enum":["r1","r2","r3"],"default":"r1"}}}],"security":[{"basicAuth":[]}],"paths":{"/cpaas/channels/whatsapp/cloud":{"get":{"tags":["WhatsApp configurations"],"summary":"Get WhatsApp configuration for API Space","description":"Retrieves all Cloud WhatsApp Channel configuration for an API Space","parameters":[{"name":"includeDeleted","in":"query","description":"Indicates whether deleted channels should be returned.","required":false,"schema":{"type":"boolean"}},{"name":"configurationStatus","in":"query","description":"Indicates the current configuration status of the configurations to be returned.","required":false,"schema":{"type":"string"}},{"name":"wabaIds","in":"query","description":"The list of wabaIds to filter by","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"phoneNumbers","in":"query","description":"An array of phone numbers for which to to filter by. If not provided, all phone numbers added to the WABA are included","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"pattern":"^\\+?[1-9]\\d{1,14}$","type":"string"}}}],"responses":{"200":{"description":"The WhatsApp channel configuration","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/whatsAppCloudConfiguration"}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}}},"post":{"tags":["WhatsApp configurations"],"summary":"Creates WhatsApp configuration","description":"Creates a new Cloud WhatsApp configuration.","requestBody":{"description":"Details of the WhatsApp Cloud Channel configuration to create","content":{"application/json":{"schema":{"$ref":"#/components/schemas/whatsAppCloudConfigurationCreate"}}},"required":true},"responses":{"202":{"description":"The request to create a WhatsApp Cloud Channel configuration was accepted"},"400":{"description":"Validation errors were found"},"401":{"description":"Unauthorized"},"409":{"description":"The Cloud configuration already exists"},"500":{"description":"Internal server error"}}}},"/cpaas/channels/whatsapp/cloud/{phoneNumber}":{"get":{"tags":["WhatsApp numbers"],"summary":"Get WhatsApp number","description":"Retrieves the WhatsApp configuration for a number.","parameters":[{"name":"phoneNumber","in":"path","description":"A WhatsApp-registered number in [E164 format](https://en.wikipedia.org/wiki/E.164) associated with a WhatsApp Business Messaging account.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The WhatsApp channel configuration","headers":{"ETag":{"description":"A unique value representing the version of the WhatsApp configuration, optionally used for optimistic concurrency control on PUT and DELETE","schema":{"type":"string"}},"Last-Modified":{"description":"The date the WhatsApp channel configuration was last updated in ISO 8601 format","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/whatsAppCloudConfiguration"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"The WhatsApp channel configuration was not found"},"500":{"description":"Internal server error"}}},"delete":{"tags":["WhatsApp numbers"],"summary":"Removes WhatsApp number","description":"Removes a WhatsApp number configuration permaently.\n<br><br>\n**Warning: This action cannot be undone!**","parameters":[{"name":"phoneNumber","in":"path","description":"A WhatsApp-registered number in [E164 format](https://en.wikipedia.org/wiki/E.164) associated with a WhatsApp Business Messaging account.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Indicates successful removal of a cloud originator number"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"The cloud originator number was not found"},"500":{"description":"Internal server error"}}}},"/cpaas/channels/whatsapp/cloud/register/{phoneNumber}":{"post":{"tags":["WhatsApp numbers"],"summary":"Registers WhatsApp number","description":"Registers a WhatsApp configuration for a number.","parameters":[{"name":"phoneNumber","in":"path","description":"A WhatsApp-registered number in [E164 format](https://en.wikipedia.org/wiki/E.164) associated with a WhatsApp Business Messaging account.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"A Cloud registration attempt was made for the WhatsApp phone number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/registrationResult"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"The WhatsApp channel configuration for the phone number was not found"},"500":{"description":"Internal server error"}}}},"/cpaas/channels/whatsapp/businessaccounts/{wabaId}/templates":{"get":{"tags":["WhatsApp templates"],"summary":"Get WhatsApp templates","description":"Retrieves the WhatsApp templates for a specific WABA.","parameters":[{"name":"wabaId","in":"path","description":"The unique WhatsApp Business Account (WABA) identifier.","required":true,"schema":{"$ref":"#/components/schemas/wabaId"}}],"responses":{"200":{"description":"The WhatsApp templates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/inline_response_200"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}}}},"/cpaas/channels/whatsapp/businessaccounts/{wabaId}/templates/{templateId}":{"get":{"tags":["WhatsApp templates"],"summary":"Get WhatsApp template","description":"Retrieves a WhatsApp template for a specific WABA.","parameters":[{"name":"wabaId","in":"path","description":"The unique WhatsApp Business Account (WABA) identifier.","required":true,"schema":{"$ref":"#/components/schemas/wabaId"}},{"name":"templateId","in":"path","description":"The unique WhatsApp template identifier.","required":true,"schema":{"$ref":"#/components/schemas/wabaId"}}],"responses":{"200":{"description":"The WhatsApp templates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/whatsAppTemplate"}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"The WhatsApp template was not found."},"500":{"description":"Internal server error"}}}}},"components":{"schemas":{"whatsAppCloudConfiguration":{"type":"object","properties":{"expiresOn":{"type":"string","description":"The UTC date the configuration expires.","format":"date-time","example":"2100-01-01T00:00:00Z"},"messagingLimitTier":{"type":"string","description":"The daily messaging tier limit.","example":"TIER_1K"},"phoneNumberId":{"type":"string","description":"The unique id for the number.","example":"1234567890123456"},"phoneNumber":{"type":"string","description":"The number in [E164 format](https://en.wikipedia.org/wiki/E.164).","example":"16315555555"},"phoneNumberName":{"type":"string","description":"The friendly display name for the number.","example":"Brand A"},"phoneNumberNameStatus":{"type":"string","description":"The friendly name for a number review status.","example":"CONNECTED"},"phoneNumberStatus":{"type":"string","description":"The numbers status.","example":"ONBOARDING"},"phoneNumberQuality":{"type":"string","description":"The messaging quality rating for the number.","example":"GREEN"},"wabaId":{"$ref":"#/components/schemas/wabaId"},"wabaReviewStatus":{"type":"string","description":"The status of the WABA review by Meta.","example":"APPROVED"},"systemUserWabaAssignmentStatus":{"type":"string","description":"User WABA assignment status.","example":"success","enum":["failed","inProgress","success"]},"creditLineSharedStatus":{"type":"string","description":"Shared credit line status.","example":"success","enum":["failed","inProgress","success"]},"webhookSubscriptionStatus":{"type":"string","description":"WhatsApp webhook subscription status.","example":"success","enum":["failed","inProgress","success"]},"phoneNumberRegistrationStatus":{"type":"string","description":"WhatsApp number registration status.","example":"success","enum":["failed","inProgress","success"]},"configurationStatus":{"type":"string","description":"WhatsApp configuration status.","example":"success","enum":["failed","inProgress","success"]},"createdOn":{"type":"string","description":"The UTC date time of when the configuration was created.","format":"date-time","example":"2025-01-01T00:00:00Z"}}},"whatsAppCloudConfigurationCreate":{"required":["phoneNumberId","wabaId"],"type":"object","properties":{"phoneNumberId":{"type":"string","description":"Originator phone number id."},"wabaId":{"type":"string","description":"WhatsApp Business account id."}}},"registrationResult":{"type":"boolean"},"wabaId":{"type":"string","description":"The unique WhatsApp Business Account (WABA) identifier.","example":"226114410888722"},"whatsAppComponent":{"title":"WhatsApp template component","type":"object","properties":{"type":{"type":"string","description":"The type of the component.","enum":["BODY","FOOTER","HEADER","BUTTONS"]},"text":{"type":"string","description":"The text for the component.","example":"My text"},"format":{"type":"string","example":"TEXT","enum":["TEXT","IMAGE","VIDEO","GIF","DOCUMENT","LOCATION"]},"parameters":{"type":"array","description":"Additional component parameters.","items":{"oneOf":[{"title":"Location details","required":["location","type"],"type":"object","properties":{"type":{"type":"string","enum":["location"]},"location":{"required":["address","latitude","longitude","name"],"type":"object","properties":{"latitude":{"type":"string","example":"37.44211676562361"},"longitude":{"type":"string","example":"122.16155960083124"},"name":{"type":"string","description":"The locations description.","example":"Philz Coffee"},"address":{"type":"string","description":"Location address.","example":"101 Forest Ave, Palo Alto, CA 94301"}}}},"description":"Location details"},{"title":"Any other parameters","type":"object","description":"Any other template parameters."}]}},"example":{"oneOf":[{"title":"Named parameters","required":["body_text_named_params"],"type":"object","properties":{"body_text_named_params":{"minItems":1,"type":"array","description":"Create an example of each parameter.","items":{"required":["example","param_name"],"type":"object","properties":{"param_name":{"type":"string","description":"The parameters name.","example":"booking_date"},"example":{"type":"string","description":"An example value for the parameter.","example":"2nd February"}}}}},"description":"Example of the parameter(s) usage when using **named** parameters"},{"title":"Positional parameters","required":["body_text"],"type":"object","properties":{"body_text":{"minItems":1,"type":"array","description":"Create an example of each parameter in the order they appear in the template.","items":{"type":"string","description":"An example value for the parameter."}}},"description":"Example of the parameter(s) usage when using **positional** parameters"}]},"buttons":{"minItems":1,"type":"array","description":"Buttons definitions for the template.","items":{"oneOf":[{"title":"Other button definiton.","type":"object"},{"title":"OTP buttons","required":["otp_type","type"],"type":"object","properties":{"type":{"type":"string","description":"The type of button based on it's action.","enum":["OTP"]},"otp_type":{"type":"string","description":"The type of OTP.","enum":["ONE_TAP","ZERO_TAP","COPY_CODE"]},"supported_apps":{"minItems":1,"type":"array","description":"The apps that can use the OTP, needed only for One-tap and zero-tap buttons only.","items":{"required":["package_name","signature_hash"],"type":"object","properties":{"package_name":{"type":"string","description":"The apps package name.","example":"com.example.luckyshrub"},"signature_hash":{"type":"string","description":"The signature hash for the app.","example":"K8a/AINcGX7"}}}}},"additionalProperties":true},{"title":"Copy code buttons","required":["example","type"],"type":"object","properties":{"type":{"type":"string","description":"The type of button based on it's action.","enum":["COPY_CODE"]},"example":{"oneOf":[{"minItems":1,"type":"array","description":"If using parameter(s) in your URL then you must provide an example value here.","items":{"maxLength":2000,"type":"string","description":"Parameter example value"}},{"maxLength":15,"type":"string","description":"For `COPY_CODE` buttons provide the value to be copied.","example":"250FF"}]}},"additionalProperties":true},{"title":"Phone number buttons","required":["phone_number","text","type"],"type":"object","properties":{"type":{"type":"string","description":"The type of button based on it's action.","enum":["PHONE_NUMBER"]},"text":{"maxLength":25,"type":"string","description":"The text to show on the button.","example":"Yes, sign me up"},"phone_number":{"maxLength":20,"type":"string","description":"The phone number to dial in [E164 format](https://en.wikipedia.org/wiki/E.164)."}},"additionalProperties":true},{"title":"Single product view buttons","required":["text","type"],"type":"object","properties":{"type":{"type":"string","description":"The type of button based on it's action.","enum":["SPM"]},"text":{"maxLength":25,"type":"string","description":"The text to show on the button.","example":"View"}},"additionalProperties":true},{"title":"Multi product view buttons","required":["text","type"],"type":"object","properties":{"type":{"type":"string","description":"The type of button based on it's action.","enum":["MPM"]},"text":{"maxLength":25,"type":"string","description":"The text to show on the button.","example":"View products"}},"additionalProperties":true},{"title":"Quick reply buttons","required":["text","type"],"type":"object","properties":{"type":{"type":"string","description":"The type of button based on it's action.","enum":["QUICK_REPLY"]},"text":{"maxLength":25,"type":"string","description":"The text to show on the button.","example":"Unsubscribe"}},"additionalProperties":true},{"title":"URL buttons","required":["text","type","url"],"type":"object","properties":{"type":{"type":"string","description":"The type of button based on it's action.","enum":["URL"]},"text":{"maxLength":25,"type":"string","description":"The text to show on the button.","example":"Yes, sign me up"},"url":{"maxLength":2000,"type":"string","description":"URL of website that loads in the device’s default web browser when the button is tapped by the user. Supports 1 variable, appended to the end of the URL string e.g. {{1}}","format":"uri"},"example":{"oneOf":[{"minItems":1,"type":"array","description":"If using parameter(s) in your URL then you must provide an example value here.","items":{"maxLength":2000,"type":"string","description":"Parameter example value"}},{"maxLength":15,"type":"string","description":"For `COPY_CODE` buttons provide the value to be copied.","example":"250FF"}]}},"additionalProperties":true}]}}}},"whatsAppTemplate":{"required":["category","components","id","language","name","parameter_format","status","sub_category"],"type":"object","properties":{"name":{"type":"string","description":"The templates name.","example":"2025_april_promo"},"parameter_format":{"type":"string","description":"Whether the parameters for the template use positonal references or named references.","example":"POSITIONAL","enum":["POSITIONAL","NAMED"]},"components":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/whatsAppComponent"},{"title":"Carousel card","required":["cards","type"],"type":"object","properties":{"type":{"type":"string","description":"The type of the component.","enum":["CAROUSEL"]},"cards":{"minItems":1,"type":"array","description":"Cards for the carousel.","items":{"required":["components"],"type":"object","properties":{"components":{"$ref":"#/components/schemas/whatsAppComponent"}}}}},"description":"Carousel card content"},{"title":"Other component","type":"object","description":"A different type of component."}]}},"language":{"type":"string","description":"The language code for the template.","example":"en_US"},"status":{"type":"string","description":"The Meta review status of the template.","example":"APPROVED","enum":["PENDING","APPROVED","REJECTED","PAUSED","DISABLED"]},"category":{"type":"string","description":"The templates category.","example":"MARKETING","enum":["MARKETING","UTILITY","AUTHENTICATION"]},"sub_category":{"type":"string","description":"The sub category for the template.","example":"CUSTOM"},"id":{"type":"string","description":"The unique id for the template.","example":"920070352646140"}},"description":"WhatsApp templates"},"inline_response_200":{"required":["data","paging"],"type":"object","properties":{"data":{"type":"array","description":"WhatsApp registered templates","items":{"$ref":"#/components/schemas/whatsAppTemplate"}},"paging":{"$ref":"#/components/schemas/inline_response_200_paging"}}},"inline_response_200_paging_cursors":{"required":["after","before"],"type":"object","properties":{"before":{"type":"string","description":"Continuation token for the previous page.","example":"QVFIU1pNYzBEY2dNM0pjNlQ5Mm0wS1FSNnRBbkJSS0hhcTdka1FXdDBCV1kxYmMyMS1DZADBZAMTd1aHhRaWEta0RXVFNSQXFKVENYQWhyVW50bndDMUEwbXhn"},"after":{"type":"string","description":"Continuation token for the next page.","example":"QVFIU2RLSVkwNzNaSkpGYjk0YnhGWE1iMHpJS0tTRzFpRzNMRzFhVUVfUHVjd0UwYUdOSFpCOC1qOGtlTWNlSnktTEk2enhyWnV6YWItSDZANV0xIbVJCVk1n"}}},"inline_response_200_paging":{"type":"object","properties":{"cursors":{"$ref":"#/components/schemas/inline_response_200_paging_cursors"}},"description":"Pagination cursors"}},"parameters":{"phoneNumberPathParameter":{"name":"phoneNumber","in":"path","description":"A WhatsApp-registered number in [E164 format](https://en.wikipedia.org/wiki/E.164) associated with a WhatsApp Business Messaging account.","required":true,"schema":{"type":"string"}},"includeDeletedQueryParameter":{"name":"includeDeleted","in":"query","description":"Indicates whether deleted channels should be returned.","required":false,"schema":{"type":"boolean"}},"configurationStatusQueryParameter":{"name":"configurationStatus","in":"query","description":"Indicates the current configuration status of the configurations to be returned.","required":false,"schema":{"type":"string"}}},"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}}},"x-readme":{"samples-languages":["curl","csharp","java","node","php","python","ruby"],"explorer-enabled":true,"proxy-enabled":true,"samples-enabled":true}}