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 24 hours 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

Init Session

POST https://studio-api-eu.ai.vonage.com/http/init

Headers

Name	Type	Description
X-Vgai-Key*	string	Account API Key per user. 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

Name	Type	Description
agent_id*	string	The ID of your published agent. You will find this on the top left right below the name of your agent.

200: OK

{
    "session_id": "88d66bd13-6d68-4cf0-adbb-dcbab67076fa",
    "session_start_time": "2022-05-03T07:56:26.958685",
    "session_expiration_time": "2022-05-03T15:56:26.958Z",
    "session_token": "eyJhbGciOiJllzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiODhkNWJkMTMtNmQ2OC00Y2YwLWFkYmItZGNiYWI2NzA3NmZhIiwiaWF0IjoxNjUxNTY0NTg2LCJleHAiOjE2NTE1OTMzODZ9.Lva2vqBfdYKVjpo283c7Ogsa_Fjrq4UUdccoi7p9OJQ"
}

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:-

https://studio-api-us.ai.vonage.com/http/init

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.

Step in Session

POST https://studio-api-eu.ai.vonage.com/http/{SESSION_ID}/step

Headers

Name	Type	Description
Authorization*	string	Bearer {{session_token}} (which you received in the Init Request)

Request Body

Name	Type	Description
input*	string	user input
parameters		You can add parameters to your query, e.g. [{"name":"userName", "value":"Tom"}]

200

{
    "session_id": "e4093097-bcea-4bc3-95a0-e1533c433553",
    "session_status": "ENDED",
    "messages": [
        {
            "text": "initial message: example_text"
        }
    ]
}

If you selected US as the region for your agent, please use this endpoint:-

https://studio-api-us.ai.vonage.com/http/{SESSION__ID}/step

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.