# Get started

In order to create an **HTTP agent**, after you clicked on "[<mark style="color:purple;">**Create Agent**</mark>](https://studio.docs.ai.vonage.com/agents-1/create-a-new-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.

![](https://3877181490-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-L_81A0PNZfdawu_TPAO%2Fuploads%2F66ighwGcAkXmv9XIFYK0%2FScreen%20Shot%202022-03-13%20at%2016.30.32.png?alt=media\&token=fb1a99f5-3608-4150-9af3-fbb376efc387)

{% hint style="info" %}
*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*.
{% endhint %}

{% hint style="success" %}
[*<mark style="color:purple;">Click here</mark>*](https://studio.docs.ai.vonage.com/agents-1/create-a-new-agent) *to learn how to build your first virtual agent.*&#x20;
{% endhint %}

## Create a new session

{% hint style="info" %}
***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.*&#x20;

*For the launch of the HTTP agent to work, make sure you have published your agent.*
{% endhint %}

Follow these text-based agents to embed your virtual agent in any platform. &#x20;

### Use Init to define the state of the Conversation

## Init Session

<mark style="color:green;">`POST`</mark> `https://studio-api-eu.ai.vonage.com/http/init`

#### Headers

| Name                                         | Type   | Description                                                                                                                                                |
| -------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Vgai-Key<mark style="color:red;">\*</mark> | string | <p>Account API Key per user.</p><p>You can find the X-Vgai-Key on the top right of your canvas. Click on the "user" icon, and then "Generate API Key".</p> |

#### Request Body

| Name                                        | Type   | Description                                                                                                          |
| ------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| agent\_id<mark style="color:red;">\*</mark> | string | <p>The ID of your published agent. </p><p>You will find this on the top left right below the name of your agent.</p> |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "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"
}
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
*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:-*

[<mark style="color:purple;">`https://studio-api-us.ai.vonage.com/http/init`</mark>](https://studio-api-eu.ai.vonage.com/http/init)
{% endhint %}

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

<mark style="color:green;">`POST`</mark> `https://studio-api-eu.ai.vonage.com/http/{SESSION_ID}/step`

#### Headers

| Name                                            | Type   | Description                                                           |
| ----------------------------------------------- | ------ | --------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | `Bearer {{session_token}}` *(which you received in the Init Request)* |

#### Request Body

| Name                                    | Type   | Description                                                                                                                |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| input<mark style="color:red;">\*</mark> | string | user input                                                                                                                 |
| parameters                              |        | <p>You can add parameters to your query, e.g. </p><p><code>\[{"name":"userName", "value":"Tom"}]</code></p><p> </p><p></p> |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
*If you selected US as the region for your agent, please use this endpoint:-*

[<mark style="color:purple;">`https://studio-api-us.ai.vonage.com/http/{SESSION__ID}/step`</mark>](https://studio-api-eu.ai.vonage.com/http/%7BSESSION__ID%7D/step)
{% endhint %}

#### You can receive multiple different "session\_status" values in the response

`AWAITING_INPUT` - agent is waiting for user response&#x20;

`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.&#x20;

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. &#x20;

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.&#x20;

![](https://3877181490-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-L_81A0PNZfdawu_TPAO%2Fuploads%2FdWIY1iZjdWuBIwJ6ycoq%2FScreen%20Shot%202022-05-03%20at%2018.40.54.png?alt=media\&token=a46005a0-63dd-488c-84bd-f7ea6a808651)

## Monitoring & Reporting

Same as for regular telephony agents, you are able to see the conversation of an HTTP agent in the [<mark style="color:purple;">reports</mark>](https://studio.docs.ai.vonage.com/agents-1/reports).

###


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://studio.docs.ai.vonage.com/http/working-with-http-agents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.