This technical reference provides detailed specifications for all WhatsApp template components, including constraints, formatting rules, and API payload structures. Use this guide when building or debugging template creation requests.

HEADER Component

An optional component for adding a title or rich media to your template. Maximum of one header per template.

Header Types

{
"type":"HEADER",
"format":"TEXT",
"text":"Your order {{1}} has shipped!",
"examples":["12345"]
}

{
"type":"HEADER",
"format":"IMAGE",
"examples":[
"https://chatapps.8x8.com/files/YOUR_FILE.png"
]
}

{
"type":"HEADER",
"format":"VIDEO",
"examples":[
"https://chatapps.8x8.com/files/YOUR_FILE.mp4"
]
}

{
"type":"HEADER",
"format":"DOCUMENT",
"examples":[
"https://chatapps.8x8.com/files/YOUR_FILE.pdf"
]
}

{
"type":"HEADER",
"format":"LOCATION"
}

Media URL Requirement

For IMAGE, VIDEO, and DOCUMENT headers, you need to provide a media URL in the examples array when creating the template. You have two options:

1. Upload to 8x8: Use the Upload Media API to obtain a permanent URL
2. Self-host: Provide your own publicly accessible HTTPS URL

8x8 Upload Endpoint:

POST https://chatapps.8x8.com/api/v1/subaccounts/{subAccountId}/files

See Also:

• File & Media Management - Complete guide for both upload and self-hosting options

BODY Component

The main text content of your template. This is the only required component and the only component that supports multiple parameters.

Specifications

API Payload Example

{
"type":"BODY",
"text":"Hi {{1}}, your order {{2}} is confirmed and will arrive by {{3}}.",
"examples":["Maria","ABC-123","Dec 15"]
}

Best Practices

• Keep it concise: Users read on mobile devices
• Use parameters wisely: Only parameterize data that changes (names, dates, IDs)
• Static text first: Start with static text for Meta review clarity
• No parameters at edges: Don't start or end with {{1}}

FOOTER Component

An optional component for adding small print, legal text, or brand attribution.

Specifications

API Payload Example

{
"type":"FOOTER",
"text":"Not you? Contact support."
}

Common Use Cases

• Unsubscribe instructions: "Reply STOP to opt out"
• Legal disclaimers: "Terms apply"
• Brand attribution: "Powered by YourCompany"
• Support contact: "Need help? Reply to this message"

BUTTONS Component

An optional component to add interactive buttons. Buttons enable users to take action with a single tap.

Button Types & Specifications

{
"type":"quick_reply",
"text":"Main Menu"
}

{
"type":"URL",
"text":"Track Order",
"url":"https://myapp.com/track/{{1}}",
"examples":["12345"]
}

{
"type":"PHONE_NUMBER",
"text":"Call Support",
"phoneNumber":"62211521",
"country":"SG"
}

{
"type":"OTP",
"otp_type":"COPY_CODE"
}

{
"type":"COPY_CODE",
"examples":["250FF"]
}

{
"type":"FLOW",
"text":"Book Appointment",
"flowId":"1234567890123456"
}

Button Combination Rules

Total Button Limit: Maximum of 10 buttons across all types combined.

Mixing Button Types:

• Quick Reply buttons can be mixed with URL/Phone buttons
• Copy Offer Code buttons can be mixed with other CTA buttons (URL/Phone/Quick Reply)
• Flow buttons can be mixed with other CTA buttons (URL/Phone/Quick Reply)
• When mixing, buttons of the same type must be consecutive (e.g., all URL buttons together, then all Quick Reply buttons together, or vice versa - do not intermix)
• OTP Copy Code buttons cannot be mixed with any other button types (must be used alone)

Valid Examples:

• ✅ [URL, URL, Quick Reply, Quick Reply]
• ✅ [Quick Reply, Quick Reply, URL, URL]
• ✅ [PHONE_NUMBER, URL, Quick Reply, Quick Reply]
• ✅ [Quick Reply, Quick Reply, Quick Reply, PHONE_NUMBER, URL]
• ✅ [COPY_CODE, URL, Quick Reply] - Copy Offer Code can mix with other CTA buttons
• ✅ [FLOW, Quick Reply, Quick Reply] - Flow button can mix with Quick Reply buttons
• ✅ [FLOW, URL] - Flow button can mix with URL buttons
• ✅ [OTP] - OTP Copy Code buttons must be used alone
• ❌ [URL, Quick Reply, URL, Quick Reply] - Invalid (intermixed)
• ❌ [OTP, Quick Reply] - Invalid (OTP Copy Code cannot mix with other types)
• ❌ [OTP, URL] - Invalid (OTP Copy Code cannot mix with other types)
• ❌ [OTP, FLOW] - Invalid (OTP Copy Code cannot mix with other types)

Desktop Display Limitations:

• Templates with 4+ buttons may not render properly on WhatsApp Desktop
• Mixed button types (URL + Quick Reply) may prompt "View on phone"
• Test templates on both mobile and desktop before launching campaigns

Button Array Structure

Buttons are defined within a BUTTONS component:

{
"type":"BUTTONS",
"buttons":[
{
"type":"URL",
"text":"Track Order",
"url":"https://myapp.com/track/{{1}}",
"examples":["12345"]
},
{
"type":"FLOW",
"text":"Book Appointment",
"flowId":"1234567890123456"
},
{
"type":"quick_reply",
"text":"Contact Support"
},
{
"type":"quick_reply",
"text":"Main Menu"
}
]
}

CAROUSEL Component

A special template type for MARKETING category that displays a horizontally scrollable list of up to 10 "cards." Each card can have its own image/video, text, and buttons.

Carousel Specifications

Card Component Requirements

Each card within the carousel must contain:

1. HEADER (Required)

   • Must be IMAGE or VIDEO format
   • Same size/format constraints as standard headers (IMAGE: max 5MB, VIDEO: max 16MB)
   • Each card can have a different image/video

2. BODY (Required)

   • Max Length: 160 characters (shorter than standard templates)
   • Supports parameters: {{1}}, {{2}}, etc.
   • Each card can have different body text

3. BUTTONS (Required)

   • Each card must have at least 1 button
   • Max 2 buttons per card
   • Button types allowed: URL (with dynamic parameter), Quick Reply
   • All cards must have the same button configuration (same number and types)

Carousel API Payload Structure

{
"language":"en_US",
"name":"product_carousel_demo",
"category":"MARKETING",
"components":[
{
"type":"body",
"text":"Hi {{1}}, check out our featured products! Special offer: {{2}}% off.",
"examples":["Alex","25"]
},
{
"type":"carousel",
"cards":[
{
"components":[
{
"type":"header",
"format":"image",
"examples":["https://chatapps.8x8.com/files/product1.jpg"]
},
{
"type":"body",
"text":"Product A - Now {{1}}",
"examples":["$49.99"]
},
{
"type":"buttons",
"buttons":[
{
"type":"url",
"text":"Buy Now",
"url":"https://mystore.com/product/{{1}}",
"examples":["product-a"]
},
{
"type":"quick_reply",
"text":"Add to Cart"
}
]
}
]
},
{
"components":[
{
"type":"header",
"format":"image",
"examples":["https://chatapps.8x8.com/files/product2.jpg"]
},
{
"type":"body",
"text":"Product B - Limited {{1}}",
"examples":["Stock"]
},
{
"type":"buttons",
"buttons":[
{
"type":"url",
"text":"Buy Now",
"url":"https://mystore.com/product/{{1}}",
"examples":["product-b"]
},
{
"type":"quick_reply",
"text":"Add to Cart"
}
]
}
]
}
]
}
]
}

Carousel Best Practices

• Consistent Design: Use similar image dimensions and styling across all cards
• Clear Value: Each card should showcase a distinct product/offer
• Actionable Buttons: Every card needs clear CTAs
• Test on Mobile: Carousels are mobile-optimized; test scrolling behavior
• Limit Parameters: Too many variables make templates hard to maintain

Parameter Formatting Rules

WhatsApp templates support two parameter types: positional and named.

Positional Parameters (Recommended)

Format: {{1}}, {{2}}, {{3}}, etc.

Rules:

• Parameters must be sequential: {{1}}, {{2}}, {{3}} (no skipping)
• Order matters when sending: parameters are matched by position
• Can be used in: BODY (unlimited), HEADER text (max 1), URL buttons (max 1 at end)

Example:

{
"type":"BODY",
"text":"Hi {{1}}, order {{2}} ships on {{3}}",
"examples":["John","ORD-123","Dec 10"]
}

When sending, provide parameters in order:

{
"type":"body",
"parameters":[
{"type":"text","text":"John"},
{"type":"text","text":"ORD-123"},
{"type":"text","text":"Dec 10"}
]
}

Named Parameters

Format: {{first_name}}, {{order_number}}, {{delivery_date}}, etc.

Rules:

• Allows providing parameters out of order when sending
• More readable for templates with many variables
• Still requires sequential numbering in some Meta systems

Example:

{
"type":"BODY",
"text":"Hi {{customer_name}}, order {{order_id}} ships on {{ship_date}}"
}

Parameter Constraints

General Rules:

• No parameters at start/end: Don't begin or end body text with a parameter
• Examples required: Every parameter must have a sample value in examples array
• Character limits apply: Parameter examples count toward component character limits
• No special characters: Don't use #, $, % in parameter values

Component-Specific Limits:

• BODY: Unlimited parameters
• HEADER (text): Max 1 parameter
• URL buttons: Max 1 parameter (must be at end of URL)
• FOOTER: No parameters allowed

Parameter Examples Requirement

When creating a template, you must provide sample values for every parameter:

{
"type":"BODY",
"text":"Hi {{1}}, your {{2}} order arrives {{3}}.",
"examples":["Maria","Premium","tomorrow"]
}

Meta uses these examples to:

• Validate template format and category
• Preview how the template will appear
• Test parameter substitution logic

Template Limits & Quotas

Per-WABA Limits

Component Limits

Related Resources

For Creating Templates:

• WhatsApp over 8x8 API - API endpoint and authentication
• Template Message API Library - Complete Create & Send payload examples
• Message Types & Templates - High-level concepts and portal guide

For Sending Templates:

• WhatsApp over 8x8 API - Send endpoint overview
• Template Message API Library - Send payload examples for all types

For Template Compliance:

• Governance, Security & Compliance - Meta's template policies
• Operations, Monitoring & Troubleshooting - Template rejection reasons and fixes

This guide provides the step-by-step process for activating your WhatsApp Business Platform account and connecting it to the 8x8 Connect portal. The "portal-first" approach uses 8x8's embedded signup flow, which is the fastest way to get started.

8x8 Account Structure & Interaction Methods

This is how 8x8 organizes your service and how you interact with it:

• 8x8 Account: Your main customer account.

• Subaccount: Logical groupings within your Account (e.g., by department, use-case, target country, etc). API calls require a subAccountId.

• Channel: Configured within a Subaccount, a Channel represents a specific communication service you've enabled (e.g., WhatsApp, SMS, Viber). For WhatsApp, this channel connects to your WhatsApp Business Phone Number to establish your sender identity.

Prerequisites & Checklist

Before you begin the setup process, ensure you have the following:

• An 8x8 Connect Account: You must have an active 8x8 Connect account with the 8x8 Messaging Apps product enabled.

• A Meta Business Portfolio: You will need a Meta Business Portfolio (formerly Business Manager) to own your WhatsApp Business Account (WABA). If you don't have one, the setup process will guide you in creating one.

• A New Phone Number: You need a phone number that is not currently associated with any WhatsApp account (neither the consumer app nor another business account). This number will be dedicated to your business profile.

• Access to the Phone Number: You must be able to receive a one-time passcode (OTP) via SMS or a voice call to the phone number you are registering.

• Admin Access: You must have administrator-level access to both your 8x8 Connect account and your Meta Business Portfolio.

Connect Meta & 8x8 (Embedded Signup)

The 8x8 WhatsApp Business Platform utilizes Meta's Embedded Signup flow. This is a secure, Meta-hosted process launched from within the 8x8 Connect portal that allows a user to create and link all necessary Meta assets to their 8x8 account.

How it Works

The embedded signup process simplifies onboarding by guiding the user through all required steps in a single, linear flow, eliminating the need for manual configuration in the Meta Business Platform.

Onboarding Flow

1. Log in to 8x8 Connect: Authenticate into the 8x8 Connect portal.

2. Initiate Onboarding: Navigate to the channel provisioning section (e.g., "Messaging Apps" > "Channels") and select to add a WhatsApp channel.

3. Launch Embedded Signup: The system will launch a Meta-hosted wizard. A pop-up window managed by Meta will open.

1. Authenticate with Meta: Log in using Meta credentials for an account with administrative access to the desired Meta Business Account.

2. Select/Create Assets: The flow will provide options to:

   • Create a new Meta Business Account or select an existing one.

   • Create a new WhatsApp Business Account (WABA) or select an existing one.

   • Create a new WhatsApp Business Profile or select an existing one.

1. Add & Verify Phone Number:

   • Provide the phone number to be associated with the WhatsApp channel.
   • Select a verification method (SMS or Voice Call).
   • Enter the 6-digit verification code received on that number.

2. Complete Flow: Upon successful verification, the Meta-hosted window will close. The flow will return the user to the 8x8 Connect portal, and the necessary identifiers will be automatically provisioned for the new channel. This new, active channel is now visible in your 8x8 Connect portal, as described in the next step.

Business Verification & Raising Limits

Meta's business verification confirms your company's legitimacy and is required to access certain platform features. WhatsApp uses this same verification to scale your messaging limits and build trust.

For more information, see About business verification.

Why Verification is Required

• Scale Messaging: Verification is the first step to move beyond the initial 250-user limit. Verified businesses can engage up to 2,000 unique customers per 24 hours and subsequently scale to 10,000, 100,000, or unlimited, based on sending volume and quality.

• Build Trust: Your verified business display name becomes visible to customers in the WhatsApp client.

• Add More Numbers: Verified businesses can register multiple phone numbers under their WABA; unverified businesses are limited.

• Apply for OBA: Verification is a prerequisite before you can request an Official Business Account (green checkmark).

How the Verification Process Works

You must complete this process in your Meta Business Portfolio's Security Centre.

1. Start Verification: Go to the Security Centre in your Meta Business Portfolio and start the process.

2. Enter Business Details: Provide your business's legal name, address, phone number, and website. These details must exactly match your official legal documents.

3. Confirm Records or Upload Documents:

   • Meta will first try to find a match in its official records.

   • If no match is found, you will be asked to upload documents.

4. Confirm Your Connection: You must prove you are associated with the business via one of these methods:

   • Email

   • Phone Call

   • SMS

   • WhatsApp Message

   • Domain Verification (uploading an HTML file to your website)

5. Wait for Review: Meta's review can take up to 14 working days.

Required Documentation (If Requested)

You may be asked to provide proof of your legal entity and your address/phone number.

• Accepted for Legal Entity: Business license, Certificate of Formation/Incorporation, Business Tax or VAT registration certificate.

• Accepted for Address/Phone: Utility bill, Bank statement, or any of the legal entity documents listed above if they show your address/phone.

• Not Accepted: Invoices, purchase orders, tax returns, website printouts, or marketing materials.

Providing false or misleading information can lead to denial. After verification, certain portfolio details (like legal name and country) become locked.

Confirm and Locate Your New Channel

After completing the Embedded Signup flow (step 3.2), your verified phone number is now an active 'Channel' in the 8x8 Connect portal. This channel is the 'sender' you will use for all portal-based activities and is the entity linked to your subAccountId for API calls.

1. In the 8x8 Connect portal, navigate to Messaging Apps > Channels.

2. You will see your newly connected WhatsApp phone number (e.g., +15551234567) listed.

3. Select this channel to view its details. Note the Channel ID and the Subaccount it is associated with. You will need the Subaccount ID for API calls.

4. This channel is now available to be selected in the Campaigns tool, 8x8 Converse, and the Automation Builder.

Send Your First Message from the Portal

The easiest way to send your first message is by using the Campaigns tool (formerly Multi-Channel Sender, or MCS).

1. Navigate to Campaigns from the main portal menu.

2. Click "Create a new campaign" and select "Messaging Apps".

3. Select the Subaccount that contains your WhatsApp channel, and then choose your WhatsApp Channel (phone number) from the "From" dropdown.

4. Add a recipient's phone number in the "Add recipients" section (e.g., by typing the number).

5. In the "Compose a message" section, you must select an approved Message Template.

   • You cannot send a freeform text message to initiate a conversation.

   • Select a pre-approved template (e.g., a "Utility" template like hello_world).

6. Click "Send your message(s)" to review and dispatch the message.

7. Test the 24-hour window: Once the recipient receives the message, have them reply. You can now use the Campaigns tool again to send them a freeform (non-template) text message, as the customer service window is now open.

Next Steps

Now that you've set up your WhatsApp channel and sent your first message, explore these resources to build on your foundation:

For Business Users:

• Message Types & Templates - Learn how to create and manage custom templates for your campaigns
• WhatsApp in 8x8 Connect - Discover how to use Campaigns, Converse, and Automation Builder
• Scenarios & Tutorials - Follow step-by-step guides for common use cases

For Developers:

• WhatsApp over 8x8 API - Start building with the API to automate messaging
• Template Message API Library - Explore template message examples with complete JSON payloads
• Interactive Message API Library - Learn how to send rich interactive messages

Important Concepts:

• Concepts & Fundamentals - Understand the 24-hour window, quality ratings, and messaging limits
• Governance, Security & Compliance - Review opt-in requirements and Meta's template policies

This page will cover the options available within 8x8 Connect to manage your WhatsApp templates.

Video Guide

This is a quick video guide that goes over the WhatsApp Template Page.

Viewing Templates

To view your existing WhatsApp Templates, you can navigate to the following page in 8x8 Connect which is under Messaging Apps > WhatsApp Templates

The page has the ability to filter by the following options:

When focusing on the Message Templates themselves, they will contain the following information:

Creating Templates

WhatsApp Templates can be created using the Create new template button in the WhatsApp templates page above. The button will generate this pop up which will ask you to fill in details about the type of WhatsApp template that you would like to submit to WhatsApp for approval.

📘WhatsApp ultimately approves these templates and will reject any templates that violate their policies. Please see WhatsApp's Business Messaging Policy page for details.

The fields that are available are:

Once you submit the message for approval, you can use the existing template page to check on it's status and whether it is approved an able to be used with your WhatsApp Sender ID through 8x8.

Deleting Templates

Templates can be deleted via the delete option that pops up when mousing over the row of an individual template.

Editing Templates

It is not possible to edit WhatsApp Templates. You can create new templates to submit for approval from WhatsApp and use those instead.

Managing Templates via API

WhatsApp Templates can be Added, Deleted and Retrieved via an API. Please see the links for details.

WhatsApp Template Change Webhook are notifications sent to you to inform about any updates or modifications to your WhatsApp template.

📘

In case you're looking for delivery notifications for Chat Apps message, please refer to Delivery receipts for outbound Chat Apps

Requirements

To receive WhatsApp template change webhook, you need:

• An account configured to use Chat Apps product.
• A webhook to indicate to us which URL 8x8 platform should send Chat Apps Business Management Updates to.

📘

You can configure your callback using Webhooks Configuration API

Retry logic

In case of connection error/timeout or HTTP response code 4XX or 5XX, there will be multiple retry attempts with progressive intervals: 1, 10, 30, 90 sec.

Webhook format

Request body description

eventDetails object description

meta object description

Sample template update webhook

{
"eventId":"0f88f5c4-fae7-4dcf-8ff2-b2990133edea",
"timestamp":"2025-01-01T00:00:00.00Z",
"provider":"WhatsApp",
"businessAccountId":<BusinessAccountId>,
"accountId":<AccountId>,
"eventType":"template_category_update",
"eventDetails":
{
"templateId":<TEMPLATE_ID>,
"templateName":<TEMPLATE_NAME>,
"templateLanguage":<TEMPLATE_LANGUAGE>,
"meta":
{
"previousCategory":"UTILITY",
"newCategory":"MARKETING"
}
}
}

{
"eventId":"0f88f5c4-fae7-4dcf-8ff2-b2990133edea",
"timestamp":"2025-01-01T00:00:00.00Z",
"provider":"WhatsApp",
"businessAccountId":<BusinessAccountId>,
"accountId":<AccountId>,
"eventType":"template_quality_update",
"eventDetails":
{
"templateId":<TEMPLATE_ID>,
"templateName":<TEMPLATE_NAME>,
"templateLanguage":<TEMPLATE_LANGUAGE>,
"meta":
{
"previousQualityScore":"UNKNOWN",
"newQualityScore":"GREEN"
}
}
}

{
"eventId":"0f88f5c4-fae7-4dcf-8ff2-b2990133edea",
"timestamp":"2025-01-01T00:00:00.00Z",
"provider":"WhatsApp",
"businessAccountId":<BusinessAccountId>,
"accountId":<AccountId>,
"eventType":"template_status_update",
"eventDetails":
{
"templateId":<TEMPLATE_ID>,
"templateName":<TEMPLATE_NAME>,
"templateLanguage":<TEMPLATE_LANGUAGE>,
"meta":
{
"status":"APPROVED",
"reason":"NONE"
}
}
}

{
"eventId":"0f88f5c4-fae7-4dcf-8ff2-b2990133edea",
"timestamp":"2025-01-01T00:00:00.00Z",
"provider":"WhatsApp",
"businessAccountId":<BusinessAccountId>,
"accountId":<AccountId>,
"eventType":"template_status_update",
"eventDetails":
{
"templateId":<TEMPLATE_ID>,
"templateName":<TEMPLATE_NAME>,
"templateLanguage":<TEMPLATE_LANGUAGE>,
"meta":
{
"status":"REJECTED",
"reason":"INCORRECT_CATEGORY"
}
}
}

{
"eventId":"0f88f5c4-fae7-4dcf-8ff2-b2990133edea",
"timestamp":"2025-01-01T00:00:00.00Z",
"provider":"WhatsApp",
"businessAccountId":<BusinessAccountId>,
"accountId":<AccountId>,
"eventType":"template_status_update",
"eventDetails":
{
"templateId":<TEMPLATE_ID>,
"templateName":<TEMPLATE_NAME>,
"templateLanguage":<TEMPLATE_LANGUAGE>,
"meta":
{
"status":"FLAGGED",
"disableInfo":{
"disableDate":"DATE"
}
}
}
}

{
"eventId":"0f88f5c4-fae7-4dcf-8ff2-b2990133edea",
"timestamp":"2025-01-01T00:00:00.00Z",
"provider":"WhatsApp",
"businessAccountId":<BusinessAccountId>,
"accountId":<AccountId>,
"eventType":"template_status_update",
"eventDetails":
{
"templateId":<TEMPLATE_ID>,
"templateName":<TEMPLATE_NAME>,
"templateLanguage":<TEMPLATE_LANGUAGE>,
"meta":
{
"status":"PAUSED",
"reason":"NONE",
"otherInfo":{
"title":"FIRST_PAUSE",
"description":"Pause description"
}
}
}
}

📘

template_correct_category_detection is a detection/advisory event only — the template's category is not changed. To clear the warning, re-categorize the template to match correctCategory.

{
"eventId":"0f88f5c4-fae7-4dcf-8ff2-b2990133edea",
"timestamp":"2025-01-01T00:00:00.00Z",
"provider":"WhatsApp",
"businessAccountId":<BusinessAccountId>,
"accountId":<AccountId>,
"eventType":"template_correct_category_detection",
"eventDetails":
{
"templateId":<TEMPLATE_ID>,
"templateName":<TEMPLATE_NAME>,
"templateLanguage":<TEMPLATE_LANGUAGE>,
"meta":
{
"category":"UTILITY",
"correctCategory":"MARKETING"
}
}
}

WhatsApp Phone Number Change Webhook are notifications sent to you to inform about changes to your business phone number's messaging limit and throughput level.

Requirements

To receive WhatsApp phone number quality change webhook, you need:

• An account configured to use Chat Apps product.
• A webhook to indicate to us which URL 8x8 platform should send Chat Apps Business Management Updates to.

📘

You can configure your callback using Webhooks Configuration API

Retry logic

In case of connection error/timeout or HTTP response code 4XX or 5XX, there will be multiple retry attempts with progressive intervals: 1, 10, 30, 90 sec.

Webhook format

Request body description

eventDetails object description

meta object description

Sample webhook

{
"eventId":"0f88f5c4-fae7-4dcf-8ff2-b2990133edea",
"timestamp":"2025-01-01T00:00:00.00Z",
"provider":"WhatsApp",
"businessAccountId":<BusinessAccountId>,
"accountId":<AccountId>,
"eventType":"phone_number_quality_update",
"eventDetails":{
"displayPhoneNumber":"15550783881",
"meta":{
"event":"UPGRADE",
"currentLimit":"TIER_10K",
"oldLimit":"TIER_1K"
}
}
}

{
"eventId":"0f88f5c4-fae7-4dcf-8ff2-b2990133edea",
"timestamp":"2025-01-01T00:00:00.00Z",
"provider":"WhatsApp",
"businessAccountId":<BusinessAccountId>,
"accountId":<AccountId>,
"eventType":"phone_number_quality_update",
"eventDetails":{
"displayPhoneNumber":"15550783881",
"meta":{
"event":"THROUGHPUT_UPGRADE",
"currentLimit":"TIER_UNLIMITED"
}
}
}

In February 2026, the deprecated fields will be removed and only maxDailyConversationsPerBusiness will be included.

{
"eventId":"0f88f5c4-fae7-4dcf-8ff2-b2990133edea",
"timestamp":"2025-01-01T00:00:00.00Z",
"provider":"WhatsApp",
"businessAccountId":<BusinessAccountId>,
"accountId":<AccountId>,
"eventType":"phone_number_quality_update",
"eventDetails":{
"displayPhoneNumber":"15550783881",
"meta":{
"event":"ONBOARDING",
"maxDailyConversationsPerBusiness":"TIER_10K"
}
}
}

{
"eventId":"0f88f5c4-fae7-4dcf-8ff2-b2990133edea",
"timestamp":"2025-01-01T00:00:00.00Z",
"provider":"WhatsApp",
"businessAccountId":<BusinessAccountId>,
"accountId":<AccountId>,
"eventType":"phone_number_quality_update",
"eventDetails":{
"displayPhoneNumber":"15550783881",
"meta":{
"event":"THROUGHPUT_UPGRADE",
"maxDailyConversationsPerBusiness":"TIER_UNLIMITED"
}
}
}

WhatsApp Account Update Webhooks are notifications sent to you to inform about updates and changes to your WhatsApp Business Account (WABA).

Requirements

To receive WhatsApp Account Update webhooks, you need:

• An account configured to use Chat Apps product.
• A webhook to indicate to us which URL 8x8 platform should send Chat Apps Business Management Updates to.

📘

You can configure your callback using Webhooks Configuration API

Retry logic

In case of connection error/timeout or HTTP response code 4XX or 5XX, there will be multiple retry attempts with progressive intervals: 1, 10, 30, 90 sec.

Webhook format

Request body description

eventDetails object description

businessVerificationInfo object description

violationInfo object description

restrictionInfo array item description

Sample Webhooks

Verification Failed

{
"eventId":"9ac6f2cb-abb7-43e6-b533-b3d7017846fd",
"timestamp":"2026-01-19T13:50:20.00Z",
"provider":"WhatsApp",
"businessAccountId":"950523421983857",
"accountId":"IntegrationTestCampaign",
"eventType":"account_update",
"eventDetails":{
"event":"BUSINESS_VERIFICATION_STATUS_UPDATE",
"businessVerificationInfo":{
"businessId":"2729063412676005",
"verificationStatus":"FAILED",
"rejectionReasons":[
"LEGAL_NAME_NOT_FOUND_IN_DOCUMENTS",
"BUSINESS_NOT_ELIGIBLE"
]
}
}
}

Verification Approved

{
"eventId":"9ac6f2cb-abb7-43e6-b533-b3d7017846fd",
"timestamp":"2026-01-19T13:50:20.00Z",
"provider":"WhatsApp",
"businessAccountId":"950523421983857",
"accountId":"IntegrationTestCampaign",
"eventType":"account_update",
"eventDetails":{
"event":"BUSINESS_VERIFICATION_STATUS_UPDATE",
"businessVerificationInfo":{
"businessId":"2729063412676005",
"verificationStatus":"APPROVED",
"rejectionReasons":[
"NONE"
]
}
}
}

Account Violation

{
"eventId":"9ac6f2cb-abb7-43e6-b533-b3d7017846fd",
"timestamp":"2026-01-19T13:50:20.00Z",
"provider":"WhatsApp",
"businessAccountId":"950523421983857",
"accountId":"IntegrationTestCampaign",
"eventType":"account_update",
"eventDetails":{
"event":"ACCOUNT_VIOLATION",
"phoneNumber":"16505552771",
"violationInfo":{
"violationType":"USER_INITIATED_CALLS_LOW_PICKUP_RATE",
"remediation":"Please identify and address the cause of user-initiated calls not being picked up and make sure the business is properly resourced to handle expected call volumes."
}
}
}

Account Restriction

{
"eventId":"9ac6f2cb-abb7-43e6-b533-b3d7017846fd",
"timestamp":"2026-01-19T13:50:20.00Z",
"provider":"WhatsApp",
"businessAccountId":"950523421983857",
"accountId":"IntegrationTestCampaign",
"eventType":"account_update",
"eventDetails":{
"event":"ACCOUNT_RESTRICTION",
"phoneNumber":"16505552771",
"restrictionInfo":[
{
"restrictionType":"RESTRICTED_USER_INITIATED_CALLING",
"expiration":"2022-01-10T20:54:17.00Z"
}
]
}
}

Direct Send API - Category Abuse Warning

Sent when category misuse is detected on the Direct Send API. No restriction is applied yet.

{
"eventId":"9ac6f2cb-abb7-43e6-b533-b3d7017846fd",
"timestamp":"2026-01-19T13:50:20.00Z",
"provider":"WhatsApp",
"businessAccountId":"950523421983857",
"accountId":"IntegrationTestCampaign",
"eventType":"account_update",
"eventDetails":{
"event":"ACCOUNT_RESTRICTION",
"violationInfo":{
"violationType":"DIRECT_SEND_UTILITY_CATEGORY_ABUSE_WARN"
}
}
}

Direct Send API - Category Abuse Strike

Sent when a 7-day (STRIKE_1), 30-day (STRIKE_2), or permanent (OFFBOARD) Direct Send restriction is applied. The example below shows a 7-day restriction; substitute the violationType value for the other strike levels.

{
"eventId":"9ac6f2cb-abb7-43e6-b533-b3d7017846fd",
"timestamp":"2026-01-19T13:50:20.00Z",
"provider":"WhatsApp",
"businessAccountId":"950523421983857",
"accountId":"IntegrationTestCampaign",
"eventType":"account_update",
"eventDetails":{
"event":"ACCOUNT_RESTRICTION",
"violationInfo":{
"violationType":"DIRECT_SEND_UTILITY_CATEGORY_ABUSE_STRIKE_1"
},
"restrictionInfo":[
{
"restrictionType":"RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES",
"expiration":"2026-01-26T13:50:20.00Z"
}
]
}
}

Direct Send API - Unban

Sent when a Direct Send restriction is lifted.

{
"eventId":"9ac6f2cb-abb7-43e6-b533-b3d7017846fd",
"timestamp":"2026-01-19T13:50:20.00Z",
"provider":"WhatsApp",
"businessAccountId":"950523421983857",
"accountId":"IntegrationTestCampaign",
"eventType":"account_update",
"eventDetails":{
"event":"ACCOUNT_RESTRICTION",
"violationInfo":{
"violationType":"DIRECT_SEND_UTILITY_CATEGORY_ABUSE_UNBAN"
}
}
}

Reference

For more information about WhatsApp Business Account webhooks and Partner-led Business Verification, see:

• Meta's Account Update Webhook Reference
• Partner-led Business Verification Documentation
• Managing Webhooks

Introduction

WhatsApp Business Calling allows businesses and customers to connect via voice calls directly within the WhatsApp app. This feature provides a seamless, familiar communication channel that customers already use daily, eliminating the need for them to switch apps or use traditional phone networks.

WhatsApp Business Calling API Overview

Watch this overview by Guilherme Gribeler, Partner Engineer at Meta, who introduces the WhatsApp Business Calling API. He covers requirements, initial setup, and dives deep into the two main use cases: User-Initiated Calling and Business-Initiated Calling.

Additional Resource: WhatsApp Business Calling API Developer Documentation

Key Benefits

WhatsApp Business Calling offers significant advantages for both businesses and customers:

For Customers

• Seamless in-app experience – No need to switch to a phone dialer; calls happen directly in WhatsApp
• No additional cost – Calls use data/WiFi, so customers don't incur phone charges
• Familiar interface – Uses the WhatsApp app they already know and trust
• End-to-end encrypted – Secure communication protected by WhatsApp's encryption
• Wide availability – Available in most regions where WhatsApp Cloud API is supported (see geographic limitations below)

For Businesses

• Branded caller ID – Display your verified WhatsApp Business profile when calling
• Higher answer rates – Customers more likely to answer calls from verified businesses
• Reduced telephony costs – Lower cost compared to traditional PSTN calls
• Integrated communication – Combine messaging and voice in a single customer journey
• Rich context – Access to conversation history when calls are placed

8x8 Implementation

8x8 delivers WhatsApp Business Calling through SIP integration only, providing a bridge between WhatsApp's VoIP infrastructure and your existing voice systems.

How it works

Customer (WhatsApp) ⟷ Meta Cloud API ⟷ 8x8 Platform ⟷ SIP ⟷ Your Contact Center/PBX

• WhatsApp voice leg terminates on 8x8 – The VoIP call from WhatsApp ends at the 8x8 platform
• 8x8 bridges to your SIP infrastructure – 8x8 initiates a SIP call to your configured endpoint
• Treat it like any inbound/outbound SIP call – Use your existing IVR, routing, queuing, and agent systems

This architecture means you can leverage your existing contact center infrastructure, routing rules, and agent workflows without major changes.

Call Types Supported

WhatsApp Business Calling supports two types of calls:

✅ User-initiated (Customer-to-Business)

Customers can call your business directly from your WhatsApp Business profile or an active conversation. This requires no special permission – customers can call during your advertised business hours.

Use cases:

• Customer support inquiries
• Sales questions
• Order status checks
• General information requests

Learn more about user-initiated calling →

✅ Business-initiated (Business-to-Customer)

Your business can initiate calls to customers via WhatsApp, but only after the customer grants explicit permission through a WhatsApp template message.

Use cases:

• Appointment reminders with callback option
• Delivery notifications with live agent connection
• Sales follow-ups
• Support callbacks for open tickets

Learn more about business-initiated calling →

High-Level Architecture

The following diagram illustrates the call flow:

Flow:

1. Customer initiates or receives a call in WhatsApp
2. Meta's Cloud API handles the WhatsApp VoIP leg
3. 8x8 receives webhooks and media from Meta
4. 8x8 initiates SIP call to your configured endpoint
5. Your system routes the call (IVR, queue, agent)
6. When answered, media is bridged end-to-end
7. Call ends when either party hangs up

Prerequisites

Before implementing WhatsApp Business Calling with 8x8, ensure you have:

WhatsApp Requirements

• WhatsApp Business Platform account (Cloud API or via BSP)
• Verified WhatsApp Business phone number enabled for calling
• WhatsApp Business profile with complete information and verification

8x8 Requirements

• 8x8 Connect / CPaaS account with WhatsApp calling feature enabled
• API credentials for authentication
• Webhook endpoint to receive call events (optional, for advanced scenarios)

Infrastructure Requirements

• SIP endpoint – One of the following:
  • Contact center platform (e.g., Five9, Genesys, NICE inContact)
  • PBX / SBC (e.g., Cisco, Avaya, AudioCodes)
  • Cloud communications platform with SIP support
• SIP trunk configuration – Ability to receive SIP calls from 8x8
• Network access – Firewall rules to allow 8x8 SIP IPs

Technical Knowledge

• Familiarity with WhatsApp Business Cloud API concepts
• Understanding of SIP protocol and call routing
• Basic webhook handling (for receiving call events)

Geographic Availability

WhatsApp Business Calling availability varies by call type and region. Please review these restrictions before implementation:

Business-Initiated Calls (BIC)

NOT available in the following countries:

• 🇺🇸 United States
• 🇨🇦 Canada
• 🇹🇷 Turkey
• 🇪🇬 Egypt
• 🇻🇳 Vietnam
• 🇳🇬 Nigeria

User-Initiated Calls (UIC)

Available in most regions where the WhatsApp Cloud API is supported.

Sanctioned Countries

All WhatsApp Business Calling features are unavailable in:

• 🇨🇺 Cuba
• 🇮🇷 Iran
• 🇰🇵 North Korea
• 🇸🇾 Syria
• 🇺🇦 Ukraine (Crimea, Donetsk, Luhansk regions)

Business Phone Number Requirements

• Your business phone number must have a country code from a supported country
• Customer phone numbers can be from any country where Cloud API is available
• Internet connectivity (WiFi or mobile data) required for all calls

Getting Started

To implement WhatsApp Business Calling:

1. Review call types – Understand user-initiated and business-initiated calling
2. Choose your scenario – Determine how you'll route calls (supported scenarios)
3. Configure WhatsApp – Set up calling on Meta's WhatsApp Business Platform
4. Configure 8x8 – Link your WhatsApp number and configure SIP delivery
5. Configure your SIP endpoint – Set up inbound routing for WhatsApp calls
6. Test end-to-end – Verify calls flow from WhatsApp to your agents

Important Considerations

Compliance and Privacy

• Follow WhatsApp Business Terms and Platform Policies
• Obtain proper consent for business-initiated calls
• Respect customer opt-out requests immediately
• Handle customer data according to GDPR, CCPA, and local regulations

Quality and Performance

• Ensure adequate network bandwidth for VoIP quality
• Monitor call success rates and audio quality
• Test from various network conditions (WiFi, 4G, 5G)
• Have fallback options for failed calls

Operational Best Practices

• Staff agents during advertised calling hours
• Set clear expectations in your WhatsApp Business profile
• Provide voicemail or IVR options when agents unavailable
• Track metrics: answer rate, AHT, customer satisfaction

Next Steps

Explore the detailed guides for each call type:

• User-initiated calling – Learn how customers can call your business
• Business-initiated calling – Learn how to call customers with permission
• Supported calling scenarios – Explore different routing and integration options

Additional Resources

• Meta Documentation:
  • WhatsApp Cloud API – User-initiated calls
  • WhatsApp Cloud API – Call settings
  • WhatsApp Cloud API – Business-initiated calls
• 8x8 Documentation:
  • Voice API Introduction
  • IVR Introduction
  • WhatsApp Business Hub

Support Channels

• Technical support: support@cpaas.8x8.com
• Sales inquiries: Contact your account manager or visit cpaas.8x8.com/en/contact-us
• Support Portal: https://support.cpaas.8x8.com/hc/en-us

What is Business-initiated Calling?

Business-initiated calling allows your business to initiate voice calls to customers via WhatsApp. Unlike user-initiated calls where the customer starts the conversation, business-initiated calls are outbound from your perspective – you're calling the customer through their WhatsApp app.

Important: Meta's WhatsApp policies require that customers explicitly grant permission before your business can call them. This protects customers from unwanted calls and ensures compliance with WhatsApp's platform rules.

Opt-in Requirement

Meta's Call Permission Policy

Before you can call a customer via WhatsApp, they must:

1. Receive a permission request via WhatsApp template message
2. Tap "Allow" to grant calling permission
3. Have an active permission window (permissions can expire)

This is different from messaging, where customers opt in by messaging you first. For calling, you must explicitly request permission even if you already have a messaging conversation.

Permission Validity

IMPORTANT: Call permissions are time-limited and must be carefully managed.

Call permissions are valid for:

• 24-hour window from the moment the customer grants permission (not from when you request it)
• Permissions can be revoked by the customer at any time through WhatsApp settings
• You must request permission again after the 24-hour period expires
• One permission = one call opportunity - don't assume you can make multiple calls on the same permission

Best practice: Request permission immediately before you intend to call (within minutes), not hours or days in advance. This ensures:

• Permission hasn't expired when you actually call
• Customer expects the call and is more likely to answer
• Better compliance with Meta's policies

Geographic Availability

⚠️ Important: Business-initiated calling has significant geographic restrictions set by Meta.

Business-initiated calls (BIC) are NOT available in:

• 🇺🇸 United States
• 🇨🇦 Canada
• 🇹🇷 Turkey
• 🇪🇬 Egypt
• 🇻🇳 Vietnam
• 🇳🇬 Nigeria

All calling features are blocked in sanctioned countries:

• 🇨🇺 Cuba, 🇮🇷 Iran, 🇰🇵 North Korea, 🇸🇾 Syria
• 🇺🇦 Ukraine (Crimea, Donetsk, Luhansk regions)

Business phone number requirements:

• Your business phone number must have a country code from a BIC-supported country
• Customer phone numbers can be from any country where Cloud API is available
• Internet connectivity (WiFi or mobile data) required for all calls

Important considerations:

• Voice quality depends on customer's network connection
• Local telecommunications regulations may impose additional restrictions
• Geographic restrictions are subject to change based on Meta's policies

To verify current availability:

• Check Meta's WhatsApp Cloud API documentation for latest updates
• Consult with your 8x8 account manager for specific regional considerations

How to Request Call Permission

Step 1: Create Permission Request Template

In Meta's WhatsApp Business Manager, create a template message specifically for requesting call permission. Templates must be approved by Meta before use.

Template category: UTILITY or MARKETING (depending on use case)

Template example 1: Generic call permission

Name: call_permission_request
Category: UTILITY
Language: en_US
Message:
Hello {{1}},
We'd like to call you via WhatsApp to discuss {{2}}. This will be a free call over data/WiFi.
Would you like to allow us to call you?
Buttons:
- [Quick Reply] Allow calls
- [Quick Reply] Not now

Variables:

• {{1}}: Customer's name
• {{2}}: Call purpose (e.g., "your recent order", "your support ticket")

Template example 2: Appointment reminder with callback

Name: appointment_callback_request
Category: UTILITY
Language: en_US
Message:
Hi {{1}},
Your appointment is scheduled for {{2}} at {{3}}.
Would you like us to call you to confirm the details?
Buttons:
- [Quick Reply] Yes, call me
- [Quick Reply] No, thanks

Variables:

• {{1}}: Customer's name
• {{2}}: Date (e.g., "tomorrow", "January 15th")
• {{3}}: Time (e.g., "2:00 PM")

Template example 3: Support callback offer

Name: support_callback_request
Category: UTILITY
Language: en_US
Message:
Hello {{1}},
We see you have a question about {{2}}. Our support team can call you on WhatsApp to help.
Would you like a callback?
Buttons:
- [Quick Reply] Yes, please call
- [Quick Reply] No, I'll wait for chat

Variables:

• {{1}}: Customer's name
• {{2}}: Issue description (e.g., "your recent order", "account setup")

Template guidelines:

• Keep messages concise and clear about why you want to call
• Explicitly mention it's a WhatsApp call (free, over data/WiFi)
• Provide context about what the call will cover
• Always include clear "Allow" and "Decline" options
• Use UTILITY category for transactional calls (appointments, support)
• Use MARKETING category for promotional/sales calls (requires 24-hour messaging window)

Step 2: Send Permission Request

Use the WhatsApp Business API (Meta Cloud API) to send the template message to your customer. Include the customer's name and the specific purpose of the call in the template parameters.

Step 3: Handle Customer Response

When the customer receives the permission request, they'll see your message with buttons to grant or decline permission:

When the customer responds to the permission request, you'll receive a webhook from Meta's Cloud API. The webhook will indicate whether the customer:

• Granted permission - They tapped "Allow calls"
• Declined permission - They tapped "Not now" or ignored the request

Store the permission status in your system with a timestamp and expiry time (typically 24 hours from when granted).

How It Works

Step-by-Step Call Flow

1. Send permission request template

   • Your system sends WhatsApp template via Meta's API
   • Template asks customer for call permission

2. Customer grants permission

   • Customer taps "Allow" button in WhatsApp
   • Meta sends webhook to your system with permission confirmation

3. Your system triggers outbound call

   • Your backend makes API request to 8x8
   • Request includes customer's WhatsApp number and call parameters

4. 8x8 signals Meta Cloud API

   • 8x8 initiates the call through Meta's Cloud API
   • Meta validates that customer has granted permission

5. Customer's WhatsApp rings

   • Customer sees incoming call with your branded business name
   • Call uses VoIP (data/WiFi), not cellular network

6. Customer answers

   • When customer picks up, call is established
   • Media path is created through Meta → 8x8 → Your SIP endpoint

7. 8x8 bridges media to your SIP endpoint

   • 8x8 initiates SIP call to your configured contact center/PBX
   • Your system routes to agent or IVR
   • Agent/system answers, two-way audio flows

8. Call proceeds normally

   • Agent speaks with customer
   • Call is recorded/logged as per your policies
   • Either party can hang up

9. Call ends

   • CDRs generated on both 8x8 and your platform
   • Webhooks sent for call completion
   • Analytics updated

Visual Call Flow

Use Cases

1. Appointment Reminders with Callback

Scenario: Medical office wants to confirm appointments

Flow:

1. Send permission request 24 hours before appointment
2. Customer grants permission
3. Call customer 1 hour before appointment
4. Automated message confirms appointment
5. Option to speak with receptionist if needed

Benefits:

• Reduces no-shows
• Provides personal touch
• Allows for last-minute rescheduling

2. Delivery Updates with Live Agent

Scenario: Package delivery running late, customer needs update

Flow:

1. Detect delayed delivery in system
2. Send permission request to customer
3. Customer grants permission
4. Call customer to explain delay
5. Agent provides ETA and resolution

Benefits:

• Proactive communication
• Reduces support ticket volume
• Improves customer satisfaction

3. Sales Follow-ups

Scenario: Customer inquired about product, needs follow-up

Flow:

1. Customer chats with sales bot on WhatsApp
2. Bot requests call permission for detailed discussion
3. Customer grants permission
4. Sales rep calls within 5 minutes
5. Close sale or schedule demo

Benefits:

• Faster sales cycle
• Higher conversion rates
• Better lead qualification

4. Support Callbacks

Scenario: Customer has complex issue, chat isn't sufficient

Flow:

1. Customer struggling with chat-based support
2. Agent requests permission to call
3. Customer grants permission
4. Agent calls to screen-share or troubleshoot
5. Issue resolved faster

Benefits:

• Improved first-call resolution
• Reduced handling time
• Better customer experience

Permission Management

Tracking Opt-ins

Your system should track customer call permissions in a database with the following information:

• Customer phone number
• Permission granted status (yes/no)
• When permission was granted
• When permission expires
• Whether permission was revoked
• Number of permission requests sent
• Last request timestamp

Key considerations:

• Limit permission requests to avoid spamming customers (e.g., max 3 requests)
• Store expiry timestamp when permission is granted (typically 24 hours)
• Immediately revoke permission when customer opts out

Permission Expiry

Implement a scheduled job (run hourly) to automatically expire permissions that have passed their validity period. Mark expired permissions as inactive in your database.

Permission Revocation

Monitor your WhatsApp webhook for opt-out keywords (e.g., "stop calls", "no calls") and immediately:

• Revoke the customer's call permission
• Add them to a do-not-call list
• Cancel any pending calls
• Send confirmation that they've been removed from the call list

Best Practices

1. Only Call When Customer Expects It

Good practices:

• ✅ Request permission immediately before calling (within minutes)
• ✅ State the specific purpose in permission request
• ✅ Call within the time frame you promised
• ✅ Limit to use cases where voice adds value over chat

Bad practices:

• ❌ Request permission for "future calls" without specific purpose
• ❌ Call hours or days after permission granted
• ❌ Use permission for different purposes than stated
• ❌ Make multiple calls on same permission

2. Respect Opt-out Requests Immediately

When a customer opts out of calls:

• Revoke their permission immediately
• Add them to your do-not-call list
• Cancel any pending calls scheduled for them
• Log the opt-out event for compliance

Response time:

• Process opt-out within 1 minute
• Cancel calls scheduled within next hour
• Never call after opt-out (obvious but critical)

3. Provide Value in Every Call

Checklist before calling:

• Is the information too complex for a message?
• Does the customer need immediate assistance?
• Will a voice conversation save time for both parties?
• Do you have something actionable to discuss?

Examples:

✅ Good: "Your package was delayed. Let's reschedule delivery for a time that works for you."

❌ Bad: "Just checking if you received our message about..."

✅ Good: "You have an appointment in 1 hour. Would you like directions or need to reschedule?"

❌ Bad: Generic "How was your experience?" calls

4. Track and Optimize

Metrics to monitor:

A/B testing ideas:

• Different permission request templates
• Timing between permission grant and call
• Agent introduction scripts
• Call purposes (transactional vs. promotional)

5. Maintain Compliance

Regulatory requirements:

• Follow TCPA (US), GDPR (EU), and local telemarketing laws
• Keep records of permissions for audit trail
• Honor Do Not Call lists
• Provide clear opt-out mechanisms

Audit trail requirements:

Maintain detailed logs of all permission-related events for each customer:

• When permission was requested and for what purpose
• When permission was granted or denied
• Permission expiry timestamp
• When calls were initiated and completed
• Call duration and outcome
• Any opt-out or revocation events

Troubleshooting

Common Issues

Problem: Call fails with "permission denied"

• Verify customer has granted permission in your database
• Check permission hasn't expired (< 24 hours old)
• Confirm customer hasn't revoked permission
• Ensure you're using correct customer WhatsApp number

Problem: Customer doesn't receive permission request

• Verify template is approved by Meta
• Check customer's WhatsApp number is correct and active
• Ensure you have an active 24-hour messaging window
• Review template message delivery status

Problem: Low permission grant rate

• Make the value proposition clear in permission request
• State specific reason for call (not generic)
• Send request at appropriate time (not late night)
• Test different template wording

Problem: High opt-out rate

• Review if calls match stated purpose
• Check call timing (not too frequent)
• Ensure agents provide value in conversation
• Survey customers who opt out for feedback

Next Steps

• User-initiated calling – Learn about inbound calls from customers
• Supported calling scenarios – Explore routing and integration options
• Voice API Introduction – Understand 8x8's voice capabilities

Additional Resources

• Meta – Business-initiated calls
• Meta – WhatsApp Platform Policy
• 8x8 Voice API Introduction
• WhatsApp Business Terms

Support Channels

• Technical support: support@cpaas.8x8.com
• Sales inquiries: Contact your account manager or visit cpaas.8x8.com/en/contact-us
• Support Portal: https://support.cpaas.8x8.com/hc/en-us

❗️

Zalo Notification Service requires templates to be approved by the Zalo team.

Contact cpaas-support@8x8.com or your account manager to submit new templates.

👍Please see Messaging API for the full API reference.

Sending a notification message

If you want to send a notification text message with custom parameters via ZNS, your request payload should look like this:

{
"user":{
"msisdn":"+84123456789"
},
"clientMessageId":"\<optionalClientMessageId\>",
"type":"template",
"content":{
"template":{
"name":"\<insertTemplateId\>",
"language":"en",
"components":[
{
"type":"body",
"parameters":[
{
"type":"text",
"text":"Ana",
"name":"customer"
},
{
"type":"text",
"text":"ChatApps",
"name":"product"
},
{
"type":"text",
"text":"24 August 2023",
"name":"date"
},
{
"type":"text",
"text":"29012398",
"name":"order"
}
]
}]
}
},
"channels":[{"channel":"ZaloNotification"}]
}

The corresponding message the user will receive:

Sample notification via ZNS

Sending an OTP message

If you want to send an OTP message via ZNS, the request payload will look like the following:

{
"user":{
"msisdn":"+84123456789"
},
"clientMessageId":"\<optionalClientMessageId\>",
"type":"template",
"content":{
"template":{
"name":"\<insertTemplateId\>",
"language":"en",
"components":[
{
"type":"body",
"parameters":[
{
"type":"text",
"name":"otp",
"text":"23124"
}
]
}
]
}
},
"channels":[
{
"channel":"ZaloNotification"
}
]
}

The corresponding message the user will receive:

Sample OTP via ZNS

Optional: Adding SMS Fallback

If you want to add a fallback to SMS, add the following fields to the "content" object in your existing JSON payload:

{
"fallbackText":"Đây là OTP của bạn: 23124. Đừng chia sẻ nó với bất cứ ai.",
"sms":{
"encoding":"AUTO",
"source":"\<senderId\>"
}
}

📘

You may find out more about SenderID here

❗️ Customer Service Window

WhatsApp only allows freeform text messages to be sent once a customer service window has started. A customer service window starts when a user initiates a conversation or when a user replies to a pre-approved template sent by the business.

This customer service window lasts 24 hours, and lasts 72 hours if the customer service window is initiated via a click-to-whatsapp ad.

Outside of the customer service window, only pre-approved WhatsApp templates can be sent to users.

👍 Please see Messaging API for the full API reference.

Freeform messages

Text message

If you want to send a text message, your request will look like this:

{
"user":{
"msisdn":"+65000000"
},
"type":"text",
"content":{
"text":"Thank you for your recent purchase from TechStore! If you have any questions or need support, reply 'HELP' to connect with our support team."
}
}

The user will receive this corresponding message:

Text message with an image

If you want to send an image with an optional text, your request will look like this:

{
"user":{
"msisdn":"+6500000000"
},
"content":{
"url":"https://www.example.com/image.jpg",
"text":"Welcome to the world of 8x8 ChatApps APIs!\nCommunications for the customer obsessed."
},
"type":"Image"
}

The user will receive this corresponding message with the corresponding image from the URL that you specify.

Template Messages

Template message with text only

Depending on the use case and content, your template submitted can be categorised as a Marketing or Utility template.

This template has a single parameter where you can specify the actual OTP code in your API call.

{
"user":{
"msisdn":"+65000000"
},
"type":"template",
"content":{
"template":{
"language":"en_GB",
"name":"<Template Name>",
"components":[
{
"type":"body",
"parameters":[
{
"type":"text",
"text":"#523534"
}
]
}
]
}
}
}

The user will receive this corresponding message:

Authentication template message

{
"user":{
"msisdn":"+65000000"
},
"content":{
"template":{
"name":"<insertTemplateName>",
"language":"en",
"components":[
{
"type":"body",
"parameters":[
{
"type":"text",
"text":"12345"
}
]
},
{
"type":"Button",
"subType":1,
"index":0,
"parameters":[
{
"type":"text",
"text":"12345"
}
]
}
]
}
},
"type":"template"
}

This will result in the following message being sent with the appropriate verification code filled in as a parameter from your API call.

In addition, you can also specify a fallback to SMS option which will automatically deliver the message to the user via SMS, if the message cannot be delivered via WhatsApp (such as if the user does not have WhatsApp). It is possible to specify a different body message to fit within the character limit of the SMS message. Please see the section below for details on SMS fallback.

Template message with image

This template has 1 image header and a predefined text body.

{
"user":{
"msisdn":"+650000000"
},
"type":"template",
"content":{
"template":{
"language":"en",
"name":"<insertTemplateName>",
"components":[
{
"type":"header",
"parameters":[
{
"type":"image",
"url":"www.example.com/image.jpg"
}
]
}
]
}
}
}

The user will receive this corresponding message. Note the text is decided in the template itself and you can have dynamic parameters in the text. The image URL itself is already dynamic.

Template message with Document

This template message allows you to send a document. In this example below we use a PDF although any valid MIME-type document should be supported.

{
"user":{
"msisdn":"+6500000000"
},
"type":"template",
"content":{
"template":{
"language":"en",
"name":"<insertTemplateName>",
"components":[
{
"type":"header",
"parameters":[
{
"type":"document",
"url":"https://example.com/links/TestPDFfile.pdf"
}
]
}
]
}
}
}

The user will receive this corresponding message with a download link to the PDF document.

📘 Note

The text and buttons are part of the original template and are NOT defined in the request body above. They are optional and you can omit them from the template.

Template message with Location

This template is a location template and it allows you to specify a set of coordinates as well as a name for a location that will be sent to the recipient.

{
"user":{
"msisdn":"+65000000"
},
"type":"template",
"content":{
"template":{
"language":"en",
"name":"<Insert Template Name>",
"components":[
{
"type":"header",
"parameters":[
{
"type":"location",
"location":{
"latitude":"38.8693",
"longitude":"-77.0536",
"name":"Metro Station",
"address":"1 Connector Drive"
}
}
]
}
]
}
}
}

The user will receive this corresponding message with a pin to indicate the user location which can open up a navigation app on their phone (such as Google Maps).

Template message with a dynamic call-to-action (CTA) button

Below is an example of a Dynamic CTA Button Message with 2 CTA buttons. Please note the number of buttons may change depending on the template you use.

{
"user":{
"msisdn":"+65000000"
},
"content":{
"template":{
"name":"<Template Name>",
"language":"en_US",
"components":[
{
"type":"body",
"parameters":[
{
"type":"text",
"text":"12345"
}
]
},
{
"type":"header",
"parameters":[
{
"type":"image",
"url":"https://fastly.picsum.photos/id/173/200/300.jpg?hmac=9Ed5HxHOL3tFCOiW6UHx6a3hVksxDWc7L7p_WzN9N9Q"
}
]
},
{
"type":"button",
"index":0,
"subType":"url",
"parameters":[
{
"type":"text",
"text":"samplecta"
}
]
}
]
}
},
"type":"template"
}

The corresponding message will appear as below where the text parameters specified above will be passed to the "Check Out" and "Call Us" Buttons

Template message with Coupon Code

Below is an example of a Coupon Code Template Message with 1 copy code button. You can use copy code button in conjunction to other marketing related templates, for example CTA button and Coupon Code button.

{
"user":{
"msisdn":"+65000000"
},
"type":"template",
"content":{
"template":{
"language":"en_US",
"name":"<Template_name>",
"components":[
{
"type":"button",
"index":"0",
"subType":"copyCode",
"parameters":[
{
"type":"couponCode",
"couponCode":"25OFF"
}
]
}
]
}
}
}

Interactive messages

Interactive message with reply buttons

These types of messages do not require to be submitted for template approval, similar to freeform messages. They can be sent in an ongoing conversation via our Automation Builder or any third-party workflow/chatbot builder.

This message type can support up to 3 reply buttons:

{
"user":{
"msisdn":"+65000000"
},
"type":"interactive",
"content":{
"interactive":{
"action":{
"buttons":[
{
"type":"reply",
"reply":{
"title":"contact-us",
"id":"option-1"
}
},
{
"type":"reply",
"reply":{
"title":"faq",
"id":"option-2"
}
},
{
"type":"reply",
"reply":{
"title":"office",
"id":"option-3"
}
}
]
},
"body":{
"text":"Welcome to 8x8 Inc. How may we help?"
},
"footer":{
"text":"This is an official message from 8x8."
},
"header":{
"type":"text",
"text":"8x8 Inc."
},
"type":"button"
}
}
}

The user will receive this corresponding message.

If the user clicks on each button, it will send the corresponding reply.

Interactive message with a list of menu options

{
"user":{
"msisdn":"+65000000"
},
"type":"interactive",
"content":{
"interactive":{
"action":{
"button":"Book Slot",
"sections":[
{
"rows":[
{
"id":"slot-1",
"title":"Monday, Oct 9",
"description":"9:00 AM - 10:00 AM"
},
{
"id":"slot-2",
"title":"Monday, Oct 9",
"description":"11:00 AM - 12:00 PM"
}
],
"title":"Oct 9, 2024"
},
{
"rows":[
{
"id":"slot-3",
"title":"Tuesday, Oct 10",
"description":"2:00 PM - 3:00 PM"
},
{
"id":"slot-4",
"title":"Tuesday, Oct 10",
"description":"4:00 PM - 5:00 PM"
}
],
"title":"Oct 10, 2024"
}
]
},
"body":{
"text":"Looking for personalized assistance? Our Customer Success team has the following slots available. Tap to select a time."
},
"footer":{
"text":"For urgent inquiries, email user@example.com"
},
"header":{
"type":"text",
"text":"Customer Success personalized sessions"
},
"type":"list"
}
}
}

This will send the corresponding message.

If the customer selects the "Book Slot" option then they will be presented with the options for

After clicking "Send" then the user will send the corresponding reply.

WhatsApp Commerce

👍 Pre-requisite: You should have a catalog created and connected to your WhatsApp Business Account (WABA)

Interactive message with a single product item from a business catalog

This type of message will feature a single item from a business catalog, it will pull information from the catalog to generate the message.

❗️ Customer Service Window

WhatsApp only allows catalog messages to be sent once a customer service window has started. A customer service window starts when a user initiates a conversation or when a user replies to a pre-approved template sent by the business.

This customer service window lasts 24 hours, and lasts 72 hours if the customer service window is initiated via a click-to-whatsapp ad.

Outside of the customer service window, only pre-approved WhatsApp templates can be sent to users.

{
"user":{
"msisdn":"+65000000"
},
"type":"interactive",
"content":{
"interactive":{
"action":{
"catalog_id":"<YourCatalogId>",
"product_retailer_id":"<YourProductRetailerId>"
},
"body":{
"text":"8x8 Shirt"
},
"footer":{
"text":"Experience the power of communication with this 8x8 Shirt!"
},
"type":"product"
}
}
}

📘 Business Catalog Values

The value for which is your Catalog ID and which is your Business ID can be found from your Catalog in the Meta Commerce Manager.

Here is what the corresponding message will look like to the customer receiving the message:

Customer Flow

Once the customer clicks View, they will be taken to a page containing the following information pulled from the business catalog.

• Item Description
• Item Price
• Item URL (as provided in the catalog)

There is also an option to message the business for any questions or clarifications.

Additionally, the customer can choose to Add to Cart, which will add the item to a shopping cart.

Once the item is added you can view the cart which will take you to the Place order screen.

Selecting Place Order will send a message to the business with the cart items, so that the business can process the order.

At this point, WhatsApp leaves it to the business to define the next steps for this order, such as requesting address information for delivery or collecting payment information. It is possible for example to use webhooks or Automation Builder to listen for a cart message for a customer and then reply accordingly.

Finally, the View sent cart option will allow the customer to confirm what items were purchased in the order.

Interactive message with a list of product items from a business catalog

This option can send multiple product items from a business catalog to a customer. This may be useful if there is a collection of items (ex. pants, shirts, hats) that the business is looking to send to a customer.

❗️ Customer Service Window

WhatsaApp only allows catalog messages to be sent once a customer service window has started. A customer service window starts when a user initiates a conversation or when a user replies to a pre-approved template sent by the business.

This customer service window lasts 24 hours, and lasts 72 hours if the customer service window is initiated via a click-to-whatsapp ad.

Outside of the customer service window, only pre-approved WhatsApp templates can be sent to users.

{
"user":{
"msisdn":"+65000000"
},
"type":"interactive",
"content":{
"interactive":{
"action":{
"catalog_id":"<YourCatalogId>",
"product_retailer_id":"<YourProductRetailerId>",
"sections":[
{
"product_items":[
{
"product_retailer_id":"<id>"
},
{
"product_retailer_id":"<id>"
}
],
"title":"Section title"
}
]
},
"body":{
"text":"8x8 Limited Edition Items"
},
"footer":{
"text":"This collection contains only the finest from 8x8.  "
},
"header":{
"type":"text",
"text":"8x8 Collection"
},
"type":"product_list"
}
}
}

📘 Business Catalog Values

The value for which is your Catalog ID and which is your Business ID can be found from your Catalog in the Meta Commerce Manager. The second set of 's can be found from each individual item in the catalog as their Content ID.

Here is what the corresponding catalog message will look like.

Customer Flow

After the customer clicks on View Items, it will appear as follows:

The customer can click on an individual item to bring up the single-item page

After selecting Add to Cart, the catalog message will now reflect items added to the cart and their amounts.

View Cart will give the option of seeing the items in the cart and then allowing the customer to Place Order.

After the customer selects Place order, this will send a message to the business containing information about the cart.

At this point, WhatsApp leaves it to the business to define the next steps for this order, such as requesting address information for delivery or collecting payment information. It is possible for example to use webhooks or Automation Builder to listen for a cart message for a customer and then reply accordingly.

View sent cart would let the customer confirm the items sent in the cart.

Optional: Adding SMS Fallback

If you want to add a fallback to SMS, add the following fields to the "content" object in your existing JSON payload. The fallbackText will be used instead of the WhatsApp Template Body.

{
"fallbackText":"This is the text that will be sent in the SMS instead of the WhatsApp Template.",
"sms":{
"encoding":"AUTO",
"source":"<senderId>"
}
}

📘 Note

You may find out more about SenderID here

Send Message in Batch

Besides using the Messaging Apps API to send messages individually, you can also send multiple messages with a single API call by defining a messages array as in the examples below.

Batch WhatsApp template message with Documents

Below is an example of a batch of messages that are using a WhatsApp Template to send documents to different users.

{
"includeMessagesInResponse":true,
"messages":[
{
"user":{
"msisdn":"+6511111111"
},
"type":"template",
"content":{
"template":{
"language":"en",
"name":"<insertTemplateName>",
"components":[
{
"type":"header",
"parameters":[
{
"type":"document",
"url":"https://example.com/links/TestPDFfile.pdf"
}
]
}
]
}
}
},
{
"user":{
"msisdn":"+6522222222"
},
"type":"template",
"content":{
"template":{
"language":"en",
"name":"<insertTemplateName>",
"components":[
{
"type":"header",
"parameters":[
{
"type":"document",
"url":"https://example.com/links/TestJSFile.js"
}
]
}
]
}
}
}
]
}

📘 Different Files / Messages

Note that we are sending two different whatsapp messages with different files attached. These messages are being sent to two different recipients.

The first recipient (+6511111111) will see this message as a PDF file was defined in their message object.

The second recipient (+6522222222) will see a different message as a different file was defined in their message object.

This example shows the flexibility of the messages array in that you can customize the message that you send for each recipient.

👍 Please see Messaging API for the full API reference.

Sending a Text Message

Text only

{
"user":{
"msisdn":"+6500000"
},
"type":"text",
"content":{
"text":"Here is your booking reference: ABC1234. For more information, visit https://8x8.com/1234!"
}
}

The corresponding message the user will receive:

Viber text messages can include URL

Sending a Rich Media Message

Image only

{
"user":{
"msisdn":"+6500000"
},
"type":"image",
"content":{
"url":"https://www.redbrick.sg/wp-content/uploads/2020/04/coleen-rivas-OZ2rS2zCjNo-unsplash-1125x1500.jpg"
}
}

The corresponding message the user will receive:

Viber Rich Media: Image only message

Text + Image