Get started
In order to create a WhatsApp agent, after you clicked on "Create Agent" select the WhatsApp option. The WhatsApp agent is a text-based agent you can effortlessly use on your WhatsApp application.
The nodes available will be slightly different than in the voice-based agent. While some capabilities are not supported in text-based agents such as the "Listen" node, there are many more features for you to explore, e.g. replying to the virtual agent via voice note and transcribing it into text in order to match with the agent's knowledge base or sending and receiving images.
Click here to learn how to build your first virtual agent.

Add a phone number to your Whatsapp agent

To create any virtual agent on the Vonage AI studio, you require a Vonage API Account. Once you have created an account, you are able to purchase one or more phone numbers on the dashboard.
You can purchase your WA phone numbers on the Vonage API Dashboard. Select "External Accounts" on the left navigation panel and start the process of setting up your WhatsApp Business Account. Once done, you will see all WA accounts and their IDs below.
To associate your WA number to your virtual agent you do so on the AI Studio. Please refrain from attaching your agent to a number via the Vonage API Dashboard.
Click on "Publish" and if you are doing this for the first time, you will be prompted to select one of the WA numbers you purchased. You can also change the WA number associated in the agent's settings on the left.
Once you have added a WA number to your agent, it will also show which agent is connected on the Vonage API dashboard.

How to set up your WhatsApp agent

You can create two different types of WhatsApp agents on the AI Studio.
  1. 1.
    Inbound -> Virtual Agent handles incoming customer support queries, e.g. FAQs (opening hours, location, etc). In this case, the user is initiating the conversation with the VA.
  2. 2.
    Outbound --> Virtual Agent engages with your customers by sending notifications and updates, e.g. confirmation messages, appointment changes, special deals, etc. Here, the VA initiates the conversation with the user.

Inbound Virtual Agent

Please make sure you have a valid WhatsApp business account created through the Vonage API Dashboard.
Once you have created the WhatsApp agent and assigned a number to it, you can go ahead and test the flow. Add the virtual number to your contacts on your phone and start the conversation by sending the first message to the agent to start the flow.
You can send anything to start your agent. The content you send will be waiting in the INITIAL_MESSAGE parameter which is saved throughout the session of the conversation.

Outbound Virtual Agent

Please make sure you have a valid WhatsApp business account created through the Vonage API Dashboard.
For this type of conversation, you will need to create a WhatsApp template message and get it approved by Facebook.
WhatsApp templates are the first message being sent from a business account to a customer, prompting them to start engaging with the Virtual agent. In order for a virtual agent to send outbound messages to customers, you’ll first need to create a WhatsApp template through your Vonage API dashboard.
Please note, that Facebook will review and approve every WhatsApp template, a process that may take up to a few days to complete.
You can read more about WhatsApp message templates on Facebook's documentation page or in Vonage APIs Support Center. If you are struggling with setting up your business account or your WhatsApp template messages, please contact our support team.
Once you have a WhatsApp message template ready and approved, you can start sending outbound messages to customers. Since the template message is set through your Nexmo Dashboard on Facebook, you will not have any visibility to it from Vonage AI Studio.
Once a message template has been sent to the customer, the Virtual Agent will only be able to catch the customer’s response to it with no representation of the message template itself.
The customer’s response to the message template will initiate the conversation flow as designed in the AI Studio by triggering the “Start” node. The actual customer input will be automatically captured as the value of the INITIAL_MESSAGE system parameter and saved throughout the session of the conversation.

How to set up your outbound virtual agent

You can jumpstart the outbound session from any platform of your choosing, e.g. Postman.
Please make sure that you have configured and set up your WhatsApp template messages correctly.
You can add dynamic parameters to your template that will change according to the value you add to your query. See the example below for "PARAM1_VALUE".
The query will look like the following -

Endpoint (mandatory)

The endpoint depends on the region you selected for your agent
For EU agents --> https://studio-api-eu.ai.vonage.com/messaging/conversation
For US agents --> https://studio-api-us.ai.vonage.com/messaging/conversation

Method (mandatory)

POST

Headers (mandatory)

X-Vgai-Key
You can find the X-Vgai-Key on the top right of your canvas. Click on the "user" icon, and then "Generate API Key".

Request Body

{
"components": [
{
"type": "header",
"parameters": [
{
"type": "text",
"text": "PARAM1_VALUE"
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "PARAM2_VALUE"
}
]
}
],
"namespace": "NAMESPACE_ID",
"template": "TEMPLATE_NAME",
"locale": "en",
"to": "TO_NUMBER",
"agent_id": "AGENT_ID",
"channel": "whatsapp"
}
If you want to create an outbound campaign sending a multitude of messages to different recipients at the same time, please contact our support team for help.

WhatsApp Best Practice

1. Save your template message in a parameter

Since template messages rarely change, it’s a good idea to save the actual message creative as a parameter value for later reference in reports. To do so, create a custom parameter and manually insert the template message creative as the parameter’s value.

2. Use the initial message to determine the flow

This is mostly relevant for inbound customer care agents.
Use the INITIAL_MESSAGE parameter value to dictate the start of the conversation by creating custom conditions based on the customer’s input. This method is extremely effective for message templates that include quick reply buttons.
In the use case below, we have two intents - Office Location and Forgot Password. If the initial message of the user is not simply "Hi there, I have a question" but "I need help resetting my password", the agent can use and attempt to classify that input immediately, without waiting for the agent to prompt the user.
Add the Classification node with your intents right after the START node. This way the agent will check if the user's initial message matches an intent and can direct the conversation accordingly.
If no match is found, then the user's input will go to the Classification node's Missed tab and the agent will prompt the user normally.

Monitoring & Reporting

Same as for regular telephony agents, you are able to see the conversation of a WhatsApp agent in the reports.
Copy link
On this page
Add a phone number to your Whatsapp agent
How to set up your WhatsApp agent
Inbound Virtual Agent
Outbound Virtual Agent
How to set up your outbound virtual agent
WhatsApp Best Practice
1. Save your template message in a parameter
2. Use the initial message to determine the flow
Monitoring & Reporting