OTT Provider Integration Project

Position: Technical Product Manager

Candidate: Nevena Ristivojević
Introduction 3

TeleSign WhatsApp API 4

MVP 4
User stories 5

Next steps after MVP is delivered 12

References 13

2
Introduction
In addition to the large number of products that Telesign offers to its customers, Telesign
has a plan to include a new communication channel, the WhatsApp API, in its offer in the
coming period.
Competitive companies such as Twilio, Infobip, and others have similar products in their
offer, but Telesign would enrich its offer and thus continue to be the market leader. With this
product, customers would have added value in the form of various benefits that the
WhatsApp service offers like end-to-end encryption, connection to Facebook, and over 1.5
billion active users.

Our team for ​Market research deals with market analysis and targeting potential customers.
In this project, the Market research team will identify clients whose markets have a large
number of WhatsApp users. The potential client can get more information about the products
that Telesign offers from the representatives of the ​Business Development team​. They
perform precise analysis and based on the sub-industry in which the client operates, decide
which products can meet the needs of the potential client. The Business Development team
presents to the client all the possibilities that Telesign offers through WhatsApp's
communication channel as well as integration with other products on offer. The ​solution
architect is the technical person in the ​Sales team​. He is there to define the flow of
communications and precisely model what the system architecture will look like. After the
sale is concluded, each client receives a dedicated person from the ​Customer Success
team​.

3
TeleSign WhatsApp API

Architecture

MVP

On the WhatsApp API implementation project, the MVP should enable the client to:
● Send a message to the end-user with phone number validation;
● Has the option of two-factor authentication;
● Analyze the status of the delivered messages and based on that information,
Telesign can form the price of his service;
● Send promotional messages and notification messages (ARN Telesign product) with
the creation of various templates;
● Send messages to a group of users;

4
User stories

System Telesign’s WhatsApp API - verify the status

of a phone number

Use Case Name Phone number’s WhatsaApp status

Primary actor Client

Priority (H,M,L) High

Goal: ​Based on the given set of phone numbers, the client receives information about the
number of users who have a valid WhatsApp account. This way, it is possible to determine
the exact number of “eligible” end-user users that can be reached through the WhatsApp
channel and how many by some other communication channels such as SMS.
It also enables the client to potentially reduce the cost of delivering messages and to
determine a more precise offer of the set of products he needs, in order to reach all
desired users.

Trigger: ​The client sends a request to send a message to Telesign's WhatsApp API for
sending messages.

Input: ​URL - header|| Authorization - header || date - header || end-user phone number
(format: + country code) - body || message type - body || message - body

Pre-conditions: ​Client has an active Business WhatsApp account. Client has acquired an
access token through a System User. Telesign has an infrastructure to communicate with
the WhatsApp API.

Normal (basic) flow of events - Scenario Steps

Actor System

1. The client sends a request containing an

array of registered phone numbers.

2. Telesign receives Client’s parameters

and makes a call to WhatsApp’s API
/v1/contacts​.
3. Telesign receives a response containing

5
 user statuses (status) and their ​WhatsApp
IDs​ (wa_id).
4. Telesign saves the WhatsApp IDs for
those numbers that returned a status of
valid. Valid users are those with a
WhatsApp account.
5. Telesign sends the information to the
Client.

6. Client receives the information how much

of end-user phone numbers are valid.
Notes: Telesign needs to repeat these
steps on a regular basis to manage Client’s
list of valid users. The results are cached in
the WhatsApp Business API client's
database for 7 days.
If too many phone numbers are checked,
without sending to them, the account will be
banned.

Alternate and Exception flows:

2.1 Bad request
a. 11000 Invalid value for parameter phone_number
b. 11001 Invalid country code for parameter phone_number
c. 11005 Invalid value for parameter customer_id
d. 11009 Invalid value for parameter message
e. 12000 Missing required parameter phone_number
f. 12009 Missing required parameter message
g. 12017 Missing required parameter message_type
3.1 Bad request
4.1 Bad request
5.1 Fail to send information to the Client

Output: ​In response, the client receives the status of end-user telephone numbers (​valid,
invalid, failed​). This information allows end-users to be segmented and how the message
can be delivered to them at a minimal cost.
WhatsApp ID for a phone number - WhatsApp IDs are needed to send messages, use
notifications, and work with groups.

Other Telesign products that can be involved: ​PhoneID, SMS API

6
System Telesign’s WhatsApp API - send message

Use Case Name Sending a message

Primary actor Client

Priority (H,M,L) High

Goal: ​Successfully send a message to the end-user

Trigger: ​The client sends a request to send a message to Telesign's WhatsApp API for
sending messages.

Input: ​URL - header|| Authorization - header || date - header || end user phone number
(format: + country code) - body || message type - body || message - body

Pre-conditions: ​The client is authenticated by Telesign. The client has an open business
WhatsApp account. The phone number is valid and has a wa_id.

Normal (basic) flow of events - Scenario Steps

Actor System

1. The client sends a request to Telesign's

WhatsApp API with the required parameters
2. Telesign authorizes the client (client_id).
3. Telesign determines if the phone number
is valid.
4. Telesign receives the Client’s parameters
and makes a call to WhatsApp’s API
/v1/contacts​.
5. Telesign forwards to WhatsApp the
parameters forwarded by the client.
6. Telesign receives a response for the
forwarded request.

7. The client gets a response from Telesign.

Alternate and Exception flows:

2.1 Authorization failed

3.1 Phone number is invalid
a. TeleSign returns the status of the number to the user
4.1 Bad request

7
 a. 11000 Invalid value for parameter phone_number
b. 11001 Invalid country code for parameter phone_number
c. 11005 Invalid value for parameter customer_id
d. 11009 Invalid value for parameter message
e. 12000 Missing required parameter phone_number
f. 12009 Missing required parameter message
g. 12017 Missing required parameter message_type

Output: ​In response, the client receives that the message was successfully sent to the
delivery phone number. The code, description, and reference ID are obtained in the
response.

Other Telesign products that can be involved:

PhoneID, ARN

8
System Telesign’s WhatsApp API - message status

Use Case Name Status of the sent message

Primary actor Client

Priority (H,M,L) High

Goal: ​Obtain the information regarding the status of messages sent to end-users to
determine the exact pricing and reach of users. The messages with status READ,
DELIVERED, and DELETED are the ones that count. Later, the number of messages with
READ status can be used as a parameter when calculating, for example, the conversion
performance of promotional campaigns.
All Possible Message Statuses:
- sent → Message received by WhatsApp server
- delivered → Message delivered to the recipient
- read → Message read by the recipient
- failed → Message failed to send
- deleted → Beginning with v2.21.3, message deleted by the user

Trigger: ​After a defined amount of time, Telesign delivers a status report to the client. The
action is realized by applying WhatsApp's WebHooks.

Input: ​WebHook URL || sent_status || callback_persist

Pre-conditions: ​The message has been sent and it has its own messageID. HTTPS
support. A valid SSL certificate.

Normal (basic) flow of events - Scenario Steps

Actor System

1. Telesign sets WebHook to retrieve data

about the sent status
2. After a defined amount of time, Telesign
sends a report to the Client.
3. Client receives status report of the
sent messages
4. Telesign can form the pricing for a
specific Client.

9
Alternate and Exception flows:
1.1 Webhook cannot be set.
2.1 Reporting failed
3.1 Client doesn’t receive a status report

Output: ​Number of chargeable messages.

Notes: In this request, attention must be paid to the time period after which we make the
report. As an example, we will mention that the statuses of delivered messages can
differ after 24 to 48 hours.

Other Telesign products that can be involved: ​SCORE

10
Next steps after MVP is delivered

After completing the MVP, clients are followed by a testing phase. The dismantling of the
product is done on real data provided by the client in the desired format (preferably CSV).

After a successful release, the client can create different templates and has the ability to
send all types of messages (voice, link, media) to end-users.

Also, the client take advantage of other features offered by the WhatsApp API, which are:

- Dashboard for monitoring and alerting;

- The ability to connect to Facebook campaigns and ads;
- Possibility of scaling.

11
References
● https://enterprise.telesign.com/api-reference/apis/rcs-api/overview
● https://enterprise.telesign.com/api-reference/apis/rcs-api/send-an-rcs-messag
e/rcs
● https://developers.facebook.com/docs/whatsapp/api/messages/message-tem
plates
● https://developers.facebook.com/docs/whatsapp/api/webhooks/outbound
● https://developers.facebook.com/docs/whatsapp/api/contacts
● https://enterprise.telesign.com/api-reference/apis/sms-api/send-an-sms/post-
messaging#responses
● https://developers.facebook.com/docs/whatsapp/api/webhooks/outbound
● https://developers.facebook.com/docs/whatsapp/api/errors#error

12