Get started
In order to create an HTTP agent, after you clicked on "Create Agent" select the HTTP option. This is a text-based agent you can integrate into any application and initialize via HTTP request.
These agents have no phone number but will be accessible via HTTP.
The nodes available will be slightly different than in the voice-based agent. Some capabilities are not supported in HTTP-based agents such as the "Listen" node.
Click here to learn how to build your first virtual agent.

Create a new session

Sessions are interactions between user and agent. One session has a time limit of 8h after which the session with the agent has to be reinitiated.
For the launch of the HTTP agent to work, make sure you have published your agent.
Follow these text-based agents to embed your virtual agent in any platform.

Use Init to define the state of the Conversation

post
https://studio-api-eu.ai.vonage.com/http/init
Init Session
The endpoint of your query depends on the region you selected for your agent. If you selected US as the region for your agent, please use this endpoint

Step in Session

Once you have the Session ID you can start the actual conversation between agent and user.
Every step will execute all nodes until the session status turns to AWAITING_INPUT and will return a flow response containing all of the executed nodes with their status, errors, and messages.
post
https://studio-api-eu.ai.vonage.com/http/{SESSION__ID}/step
Step in Session
If you selected US as the region for your agent, please use this endpoint

You can receive multiple different "session_status" values in the response

AWAITING_INPUT - agent is waiting for user response
ENDED - conversation flow has ended and reached the last node in the conversation. This can be either because you added an "end call" node or this node is not connected to the following one.

HTTP Agent Best Practices

Save the Initial User Input

The initial user input will be automatically captured as the value of the INITIAL_MESSAGE system parameter and saved throughout the session of the conversation.

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.
In the use case below, we have two intents - Office Location and Forgot Password. If the initial message of the user is not just "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 an HTTP agent in the reports.

Copy link
On this page
Create a new session
Use Init to define the state of the Conversation
post
Init Session
Step in Session
post
Step in Session
HTTP Agent Best Practices
Save the Initial User Input
Use the initial message to determine the flow
Monitoring & Reporting