Aritic PinPoint and WhatsApp Integration

The Twilio API for WhatsApp enables you to reach over 1.5 billion users on WhatsApp using a simple REST API, all in Twilio’s Programmable Messaging platform. WhatsApp is the most popular OTT app in many parts of the world. If you’re trying to reach – and better converse with – users in LATAM, EMEA, and APAC you need to consider using WhatsApp. Learn More about WhatsApp.
Twilio API for WhatsApp is now available in early access, which allows developers to start building and prototyping in a sandbox. In order to launch apps in production, you can request access to enable WhatsApp on your Twilio number. WhatsApp is currently opening up this access in a Limited Availability program, where WhatsApp approval is required for all customers who wish to create their own profiles.
WhatsApp Opt-In Requirements
WhatsApp requires that your application implement explicit user opt-ins to deliver messages over WhatsApp. You may gather this opt-in via a web page or mobile app (for example during your signup flow, in account settings, via SMS, etc.) Sending users messages without an opt-in may result in users blocking your business and suspension of your Whatsapp business account.
Using Phone Numbers with WhatsApp
On WhatsApp, users message each other using phone numbers. To send and receive messages on WhatsApp using the Twilio Programmable Messaging API you’ll need a phone number as well. The Twilio API addresses WhatsApp users and your numbers using a prefixed address format:
whatsapp:
Twilio Sandbox for WhatsApp
Twilio Sandbox for WhatsApp allows you to prototype with WhatsApp immediately, without waiting for your Twilio number to be approved for WhatsApp.
It is pre-provisioned with a Twilio phone number that is shared across all sandbox users. You can pick from a list of sandbox numbers to use when you activate the sandbox via the WhatsApp console here.
whatsapp-activate-sandbox.png
Joining a Sandbox

In order to send or receive WhatsApp messages to a user from the Sandbox, you must first have them join the sandbox.
Send “join ” to your Sandbox number in WhatsApp to join your Sandbox, and we’ll reply with a confirmation that you’ve joined. Your sandbox keyword can be found in the console.
Once they join, they will only receive messages from your specific Sandbox. To disconnect from the sandbox, they can reply to the message from WhatsApp with `stop`, or switch to a different sandbox by messaging `join `.
This limitation does not exist on your own Twilio number that you enable for WhatsApp.
Enabling WhatsApp with a Twilio Number
In order to use WhatsApp messaging in production apps, you need to enable WhatsApp on your Twilio number. WhatsApp is currently opening up this access in a Limited Availability program, where WhatsApp approval is required for all customers who wish to create their own profiles.
In order to provision your own numbers, visit the WhatsApp Console and submit a request for approval from WhatsApp. Once approved, you will be able to select your Twilio numbers and apply for them to be WhatsApp enabled.
Verifying WhatsApp Enabled Numbers
Name Description
Verified WhatsApp has verified that an authentic brand owns this account. A Verified account has a green checkmark badge in its profile. Very few businesses will be WhatsApp verified. Being verified on Facebook or Instagram will not help your business be WhatsApp verified.
Confirmed WhatsApp has confirmed that the phone number of this account matches the phone number for this business. A confirmed account has a gray checkmark badge in its profile.
Regular An account that is using one of WhatsApp’s business products, but hasn’t been confirmed nor verified by WhatsApp. A business account has a gray question mark badge in its profile.
How Your Business Appears to Users
Depending on your number type, users will see different things. However, if a user has already saved the business number in their address book, the Verified Name will not take precedence; the name from the address book will always be displayed. The phone number will still be visible in the contacts view. Please be prepared for users who may try to call this number and have a plan for how to handle these incoming calls.
If the number is Verified, the Verified Name will be visible in the chat list, chat screens, chat groups, and contact view instead of the phone number. There will be a green “Verified” checkmark in the contact view.
WhatsApp Verified Example
WhatsApp Verified business chat page example
If the number is Confirmed, the Verified Name will only be visible in the contact view. All other views will show the phone number. The contact view will show a gray “Confirmed” checkmark with the verified name in smaller text.
WhatsApp Confirmed business label
WhatsApp confirmed business on chat page
If it is a Regular number, the Verified Name will only be visible in the contact view, all other views will show the phone number. The contact view will show the account is a business account with the verified name in smaller text.
Unconfirmed regular business appearance on WhatsApp
All other views will only show the phone number of your business.
Getting Verified with Whatsapp
By default, all numbers are in the “Regular” state. Once Twilio has successfully enabled your number for WhatsApp, Twilio will submit it to WhatsApp to be Verified. WhatsApp will review the request and your business and determine which level to assign it.
Test accounts will not be verified; only official accounts will be able to get verified.
Sending Notifications
WhatsApp requires that business initiated Notifications sent by your application be templated and pre-registered, with the exception of messages sent as a reply to a user initiated message (see the Conversational Messaging on WhatsApp section for more details).
WhatsApp Message Template Format
A WhatsApp Message Template contains the full body of the message, with the parameters represented as placeholders using the format below.
For example, the message:
Hi Joe Barone! Thanks for placing an order with us. We’ll let you know once your order has been processed and delivered. Your order number is O12235234
can be templatized as:
Hi {{1}}! Thanks for placing an order with us. We’ll let you know once your order has been processed and delivered. Your order number is {{2}}
The template uses numbered placeholders `{{x}}` for each variable in the message. Each variable can be replaced with text that contains letters, digits, special characters, or spaces. Newlines (`n`) are not permitted in the variable values.
A WhatsApp Message template must have at least one parameter, and can only contain text, emojis or WhatsApp-specific formatting.
Templates pre-registered for the Sandbox
If you are developing with the sandbox, you can only use the following templates that we have pre-provisioned for you:
Your {{1}} appointment is coming up on {{2}}.
Your {{1}} appointment is coming up on {{2}}. Reply with {{3}} or {{4}}
Your {{1}} order of {{2}} has shipped and should be delivered on {{3}}. Details : {{4}}
Your {{1}} code is {{2}}
Registering your own templates
You can register and manage your templates in the Console once your Twilio number is enabled for WhatsApp.
Send a WhatsApp message using a template
Twilio supports sending WhatsApp templated messages without requiring a change in how you use the Twilio Programmable Messaging API.
In order to send a templated message, you include the full body of the message in the API call. Twilio will send the message as an templated message if it matches one of the approved templates. If the Body does not match a pre-registered template, the message will be sent as a freeform message, which may fail if it is outside a WhatsApp session (see below).
For the example above, you would send:
Body=“Hi Joe! Thanks for placing an order with us. We’ll let you know once your order has been processed and delivered. Your order number is O12235234”
Send a message with WhatsApp
Conversational Messaging on WhatsApp

To have a 2 way conversation with a user, you need to receive messages from them. Users can send you a message in response to a templated notification or directly (see Discovery section below).
WhatsApp Session
A WhatsApp session begins with a user initiated message to your app. Sessions are valid for 24 hours after the most recently received message, during which time you can communicate with them using free form messages. In order to send a message outside the 24 hour Session window, you must use a pre-approved template (see Sending Notifications section above).
Discovery
You can have customers initiate a conversation with you on WhatsApp via URL schemes, embedded in web / mobile apps. If the user has WhatsApp IOS, Android or desktop installed, clicking the deep link will open a conversation with you inside the app.
Deep link format : whatsapp://send?phone=&text=Hello!
Configuring inbound message webhooks
When customers send you a WhatsApp message, Twilio sends a web hook to your application. You can configure the URL that Twilio sends a web hook to for inbound messages on the sandbox page and the WhatsApp enabled numbers page.
Optionally, on the same page, you can configure a Fallback URL that Twilio sends a web hook to, in the event of a fatal error while executing your primary webhook. When making the request to your Fallback URL Twilio will submit the ErrorCode and ErrorUrl parameters, indicating the error code of the failure and what URL the failure occurred on.
Receiving a WhatsApp message
The web hook for inbound messages uses the same format as incoming SMS messages, with the exception that To and From addresses will be set to WhatsApp addresses (whatsapp: and whatsapp:<User’s E.164 phone number>) respectively.
Support for Inbound media and location is coming soon.
For details on the data provided in the callback see the Twilio’s Request documentation.
Responding to incoming messages with TwiML
WhatsApp incoming messages are fully supported by TwiML, allowing you to seamlessly use your existing SMS app with WhatsApp. See here for more docs on [how to use TwiML]().
Sending a freeform WhatsApp message using the API
Within a WhatsApp session, you can send freeform messages using the Programmable Messaging API.
Support for sending media in outbound messages is coming soon.
Monitor the status of your WhatsApp outbound message
In order to receive real time status updates for outbound messages, you can choose to set a Status Callback URL that Twilio will web hook to each time your message status changes to one of the following: queued, failed, sent, delivered.
You can set the Status Callback URL in the console (here for sandbox and here for your WhatsApp numbers), or when you send a outbound message and include the StatusCallbackUrl parameter.
If you set the Status Callback URL, Twilio will POST the MessageSid along with the other standard request parameters as well as MessageStatus and ErrorCode.
The parameters Twilio sends to your callback URL include all its standard request parameters and some unique messaging parameters. You can see the full list in the API Reference for the Message resource.
Read Receipts
An additional web hook will be sent to the Status Callback URL when the end user opens the message (if user has enabled Read status tracking in WhatsApp) . This callback will show a status of delivered and a new parameter entitled EventType with a value of READ.
Formatting in WhatsApp messages
WhatsApp allows text, emojis and some formatting in messages. To format all or part of a message, use these formatting symbols:
Formatting Symbol Example
Bold Asterisk (**) Your total is *$10.50**.
Italic Underscore (_) Welcome to _WhatsApp_!
Strike-through Tilde (~) This is ~better~ best!
Code / Pre-formatted Three backticks (“`) “`print ‘Hello World’;“`

Leave a Reply

Your email address will not be published. Required fields are marked *