WhatsApp Now API Documentation

Introduction

Welcome to Message Central's product WhatsApp Now API documentation. Here you will find details to learn about, try, and implement each of the use-cases of WhatsApp Business API platform. WhatsApp Now is a  comprehensive solution for integrating with the official WhatsApp Business APIs. Our product leverages the robust and widely-used WhatsApp platform to enable businesses to communicate seamlessly with their customers, providing a reliable and efficient messaging service.

Prerequisites for using WhatsApp Now

Before you begin with API integration, ensure you have:

1. Verified Facebook Business Manager
2. Account on Message Central
3. Linkage of your Facebook business account with Message Central
4. A phone number that needs to be verified and used with Message Central

Help and Support

For implementation support and any feedback, please reach out to us at operations@messagecentral.com

Understanding WhatsApp Messaging

WhatsApp Business Solution messages can only be sent by businesses that have been approved by Meta. This business profile will also have a green verified label to indicate that it is a legitimate business.

The advantage of WhatsApp is that the identifier of users on the platform is their mobile phone number.

Rules for Messaging Customers

WhatsApp has a concept of a 24 hour customer care window, during which a business can freely message an end user. The 24 hour window can be initiated in two ways:

1. An end user sends a message to the business
2. A business sends a templated message to the end user. The 24 hour window starts as soon as the end user replies.

Templates must be approved by Meta before they can be used to send messages to an end user. When the 24 hour window expires, a new 24 hour customer care window must be initiated again. It is important to be aware that 24 hour customer care windows are not the same as the 24 hour billable conversation window.

WhatsApp Conversation-Based Pricing

Message Central offers a Conversation-Based Pricing model for WhatsApp messaging. This is in line with the pricing model introduced by WhatsApp at the start of February 2022.

What is a conversation?

A conversation is any number of messages sent within a 'session', which is defined as a 24 hour period starting from the time the first message is sent by the business.

Who initiates a conversation?

A conversation can be initiated either by a customer (user-initiated) or business (business-initiated), but in either case the 'session' begins with the first message sent by the business.

How does the pricing per conversations work?

The pricing for WhatsApp messaging is priced per conversation. Starting June 1st, this is priced per conversation and conversation type. There are now four conversation categories, each of which are charged at different rates:

1. Utility Conversation - Enable the completion of a particular, agreed-upon request or transaction or provide a customer with an update about an ongoing transaction, including post-purchase notifications and regular billing statements.
2. Authentication Conversation - Enables businesses to utilize one-time passcodes to verify users at various login stages, if necessary (e.g. account verification, account recovery, integrity challenges)
3. Marketing Conversation - Business-initiated conversations to market a good or service to customers, such sending pertinent offers to customers who have opted in. This would also include any business-related interaction that is not an authentication or utility conversation.
4. Service Conversation - User-initiated discussions that assist consumers in getting answers to their questions.

WhatsAppNow APIs

Message Central facilitates the sending of messages over various communication channels, including SMS, WhatsApp, RCS (Rich Communication Services). This API provides robust features and flexible options to meet diverse messaging needs. WhatsApp Now is a product of Message Central which is based on official WhatsApp Business APIs.

Use Case Scenarios

• Promotional Campaigns: Use WhatsApp Now to send promotional as well as utility messages to customers via WhatsApp. Send multimedia and documents directly through WhatsApp. Deliver personalized messages, notifications, and updates to enhance customer satisfaction and loyalty to enhance your customer experience.
  
• Live-Chat Messages: Send and receive messages, multimedia, and documents directly through WhatsApp, ensuring timely and effective communication with your audience.
  
• OTP Verification: Implement a secure OTP delivery system for user authentication, choosing between SMS, WhatsApp, or email based on user preferences and security requirements.

Also, the following parameters need to be sent while using WhatsAppNow APIs;

Rest API Base URLs:

All Platform API endpoints below should be prefixed with the following URL:

https://cpaas.messagecentral.com

Generate Token

When using the WhatsApp Now APIs to create templates, send text messages and broadcast messages, the initial call should be to the token generation API. This API returns a token that must be included in all subsequent calls. An authentication token is needed to validate the user and should be included in the header section of each request.

Request Parameters:

Request URL Path:

/auth/v1/authentication/token 

cURL

1curl --location 'https://cpaas.messagecentral.com/auth/v1/authentication/token?customerId=<CustomerId>&key=<Base64 Encrypted password>&scope=NEW&country=91&email=test@messagecentral.com' \
2--header 'accept: */*'
3

‍

NOTE: To convert a cURL command into code using Postman, open Postman, import the cURL command via the "Import" button, and then generate the code in your preferred language by clicking the "Code" button on the right side of the request.

Response JSON

A successful response will return a 200 status code.

1{
2      "status": Integer,
3      "token": "String"
4} 

Create Template

You can create templates of various types and categories, as well as creating multiple language variations of a template. When creating templates with multiple language versions, make sure to be consistent with translations across the versions.

Make sure that your templates follow WhatsApp Message Template Guidelines. Not correctly following the guidelines can impact on templates being approved.

‍

Approval Process

Templates need to be approved by Meta before they can be used in a WhatsApp message. When created, templates initially have a status of PENDING. Once approved, they will have a status of APPROVED, and can then be used.

Template Categories

• UTILITY: Enable the completion of a particular, agreed-upon request or transaction or provide a customer with an update about an ongoing transaction, including post-purchase notifications and regular billing statements.
• AUTHENTICATION: Enables businesses to utilize one-time passcodes to verify users at various login stages, if necessary (e.g. account verification, account recovery, integrity challenges).
• MARKETING: Business-initiated conversations to market a good or service to customers, such sending pertinent offers to customers who have opted in. This would also include any business-related interaction that is not an authentication or utility conversation.

To createTemplate below are the request parameters. The authentication token is required to create a template which is generated by the generated token API (which you can find above in Introduction section)

Request URL Path:

/verification/v3/template

Request Parameters:

cURL

1curl --location 'https://cpaas.messagecentral.com/verification/v3/template' \
2--header 'authToken: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OTI2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrEdL0PK3sQW4PgZBWRUCvKDkoSRoDAdXhXy9rx' \
3--form 'phoneNumber="919457888189"' \
4--form 'name="template_without_media"' \
5--form 'language="en_US"' \
6--form 'category="MARKETING"' \
7--form 'headerFormat="TEXT"' \
8--form 'header="Congratulations"' \
9--form 'body="Hello Your account recharge of ₹100 is successful. Please use our services and enjoy!"' \
10--form 'footer="Type \"STOP\" to unsubscribe"'

‍

cURL

1curl --location 'https://cpaas.messagecentral.com/verification/v3/template' \
2--header 'authToken: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OTI2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrEdL0PK3sQW4PgZBWRUCvKDkoSRoDAdXYh9rxa' \
3--form 'phoneNumber="919457888189"' \
4--form 'name="template_without_media"' \
5--form 'language="en_US"' \
6--form 'category="MARKETING"' \
7--form 'headerFormat="TEXT"' \
8--form 'body="Hello Your account recharge of ₹100 is successful. Please use our services and enjoy!"' \
9--form 'footer="Type \"STOP\" to unsubscribe"' \
10--form 'file=@"/C:/Users/Kunal Suryawanshi/Downloads/Media (9).png"'

‍

Response JSON (without & with Media Templates):

A successful response will return a 200 status code.

1{
2    "responseCode": 200,
3    "data": {
4        "data": {
5            “name”: “example_template”,
6            "id": "790937216444187",
7            "status": "PENDING",
8            "category": "MARKETING"
9        }
10    }
11}

A successful response will return a 200 status code.

Advisory for creating Template

1. Name - The name of the template should always be in small letters. Also, in case of multiple words please add a “_” in between 2 words (eg: tes_template_01)
2. Variable template - To create a variable template, you need to add placeholders and their body values mandatorily in while creating a request for such a template. 

Variables - They are always added in two curly braces, and in numeric increasing
  order, otherwise your template will get rejected.
bodyValue - These are examples of what will go inside the variable values. Since
these are form data, hence in case of more than 2 variables, separate them by
spaces.

‍Sample message -  Hello {{1}}, get 50% discount by applying the coupon  code {{2}} latest by {{3}}bodyValue(for above message) - “Kunal MSGCTL50 20thJune”, here Kunal  is an example of 1st bodyValue and so on.

3. Character limit - A text message can be a max of 4096 characters long.

Error Codes for Create Template

Check Template Status

This allows you to monitor the status of your message templates submitted for approval on WhatsApp. This API provides real-time updates on whether your templates are approved, pending, or rejected, ensuring you stay informed about their availability for use.

Request Parameters:

cURL

1curl --location --request GET 'https://cpaas.messagecentral.com/verification/v3/template' \
2--header 'authToken: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OTI2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrEdL0PK3sQW4PgZBWRUCvKDkoSRoDAdYXh9rxa' \
3--form 'phoneNumber="919547888189"' \
4--form 'templateId="205681076471259"' \
5--form 'templateName="test_template"'

‍

Response JSON

A successful response will return a 200 status code.

1{
2    "name": "prod_test_temp_wmedia_1",
3    "components": [
4        {
5            "type": "HEADER",
6            "format": "TEXT",
7            "text": "Congratulations!"
8        },
9        {
10            "type": "BODY",
11            "text": "Your account recharge of $100 is successful. Please use our services and enjoy!"
12        },
13        {
14            "type": "FOOTER",
15            "text": "Type \"STOP\" to unsubscribe"
16        }
17    ],
18    "language": "en_US",
19    "status": "APPROVED",
20    "category": "UTILITY",
21    "id": "205681076471259"
22}

Error Codes for Get Template Status

Send Broadcast

To send a WhatsApp broadcast to mobile numbers, the following request parameters are required. An authentication token, generated by the token generation API, is necessary to send the template messages via broadcast.

Request URL Path:

/verification/v3/send

Request Parameters:

NOTE: The template used must all be APPROVED templates from Meta.

Please find the Sample file format  in  XLXS format below:

Where ‘var1’, ‘var2’, and ‘var3’ are placeholders for variables. If an enterprise wants to send a customized message using file upload, the message field should be formatted as follows:

Sample message - Hello {{1}}, get 50% discount by applying the coupon {{2}} latest by {{3}}

cURL

1curl --location 'https://cpaas.messagecentral.com/verification/v3/send?flowType=WHATSAPP&senderId=919457848169&type=BROADCAST&templateName=template_without_media_1' \
2--header 'authToken: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OTI2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrEdL0PK3sQW4PgZBWRUCvKDkoSRoDAdYXh9rxa' \
3--form 'file=@"/C:/Users/Kunal Suryawanshi/Documents/Test_WA_API.xlsx"'

‍

Response JSON

A successful response will return a 200 status code.

1{
2    "responseCode": 200,
3    "message": "SUCCESS",
4    "data": null
5}
6

Error Codes for Send Broadcast

Send Chat Messages

To send a WhatsApp message(chat message) to a mobile number the following request parameters are required. An authentication token, generated by the token generation API, is necessary to send any messages over live-chat.

Request URL Path:

/verification/v3/send

Request Parameters:

cURL

1curl --location --request POST 'https://cpaas.messagecentral.com/verification/v3/send?countryCode=91&flowType=WHATSAPP&mobileNumber=7715836906&senderId=919457888189&type=CHAT&message=Welcome%20to%20Message%20Central' \
2--header 'authToken: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OTI2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrEdL0PK3sQW4PgZBWRUCvKDkoSRoDAdYXh9rxa'

‍

Response JSON

A successful response will return a 200 status code.

1{
2    "responseCode": 200,
3    "message": "SUCCESS",
4    "data": {
5        "verificationId": null,
6        "mobileNumber": "917715836906",
7        "responseCode": "200",
8        "errorMessage": null,
9        "timeout": null,
10        "smsCLI": null,
11        "transactionId": "wamid.HBgMOTE3NzE1ODM2OTA2FQIAERgSOEFFNUM5MTFDRUVBMDUzMDFGAA=="
12    }
13}

Error Codes for Chat Messages

Setup Webhook for Inbound Messages

Before you can start receiving notifications you will need to create an endpoint on your server to receive notifications.

Whenever a trigger event occurs, the Message Central’s WhatsApp Business Platform sees the event and sends a notification to a Webhook URL you will  specify. You can get two types of notifications:

1. Received messages: This alert lets you know when you have received a message. These can also be called "inbound notifications" throughout the documentation.
2. Message status: This alert lets you know when the status of a message has changed —for example, the message has been read or delivered. These can also be called "outbound notifications."

To subscribe to Webhooks, you will need to follow these steps:

1. Information Required:some text
   1. Customer ID
   2. Brand Name
   3. Registered Email ID
   4. Callback URL
      
      
2. Submission Instructions: Please send the above information to operations@messagecentral.com with the subject line "WhatsApp Webhook Configuration with Message Central".
   
   
3. Callback URL Specifications: Ensure your callback URL is accessible and capable of receiving HTTP POST requests containing JSON payloads with status updates. Upon triggering, the endpoint will receive the following JSON payload and it must respond with 200 .

‍