Get an agent's reply

curl --request POST \
  --url https://app.voho.ai/v1/agents/{id}/reply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "وين طلبي؟ رقمه سبعة تسعة واحد اثنين",
  "history": [
    {
      "text": "<string>"
    }
  ],
  "variables": {
    "customer_name": "أحمد",
    "branch": "الملز"
  },
  "audio": true
}
'

import requests

url = "https://app.voho.ai/v1/agents/{id}/reply"

payload = {
    "text": "وين طلبي؟ رقمه سبعة تسعة واحد اثنين",
    "history": [{ "text": "<string>" }],
    "variables": {
        "customer_name": "أحمد",
        "branch": "الملز"
    },
    "audio": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    text: 'وين طلبي؟ رقمه سبعة تسعة واحد اثنين',
    history: [{text: '<string>'}],
    variables: {customer_name: 'أحمد', branch: 'الملز'},
    audio: true
  })
};

fetch('https://app.voho.ai/v1/agents/{id}/reply', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.voho.ai/v1/agents/{id}/reply",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'text' => 'وين طلبي؟ رقمه سبعة تسعة واحد اثنين',
    'history' => [
        [
                'text' => '<string>'
        ]
    ],
    'variables' => [
        'customer_name' => 'أحمد',
        'branch' => 'الملز'
    ],
    'audio' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.voho.ai/v1/agents/{id}/reply"

	payload := strings.NewReader("{\n  \"text\": \"وين طلبي؟ رقمه سبعة تسعة واحد اثنين\",\n  \"history\": [\n    {\n      \"text\": \"<string>\"\n    }\n  ],\n  \"variables\": {\n    \"customer_name\": \"أحمد\",\n    \"branch\": \"الملز\"\n  },\n  \"audio\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.voho.ai/v1/agents/{id}/reply")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"وين طلبي؟ رقمه سبعة تسعة واحد اثنين\",\n  \"history\": [\n    {\n      \"text\": \"<string>\"\n    }\n  ],\n  \"variables\": {\n    \"customer_name\": \"أحمد\",\n    \"branch\": \"الملز\"\n  },\n  \"audio\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.voho.ai/v1/agents/{id}/reply")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"وين طلبي؟ رقمه سبعة تسعة واحد اثنين\",\n  \"history\": [\n    {\n      \"text\": \"<string>\"\n    }\n  ],\n  \"variables\": {\n    \"customer_name\": \"أحمد\",\n    \"branch\": \"الملز\"\n  },\n  \"audio\": true\n}"

response = http.request(request)
puts response.read_body

{
  "reply": "<string>",
  "greeting": "<string>",
  "audio": "<string>",
  "content_type": "audio/mpeg",
  "cost_cents": 123
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API token."
  }
}

{
  "error": {
    "code": "insufficient_credit",
    "message": "Your credit balance is exhausted. Top up to continue."
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

POST

agents

{id}

Get an agent's reply

curl --request POST \
  --url https://app.voho.ai/v1/agents/{id}/reply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "وين طلبي؟ رقمه سبعة تسعة واحد اثنين",
  "history": [
    {
      "text": "<string>"
    }
  ],
  "variables": {
    "customer_name": "أحمد",
    "branch": "الملز"
  },
  "audio": true
}
'

import requests

url = "https://app.voho.ai/v1/agents/{id}/reply"

payload = {
    "text": "وين طلبي؟ رقمه سبعة تسعة واحد اثنين",
    "history": [{ "text": "<string>" }],
    "variables": {
        "customer_name": "أحمد",
        "branch": "الملز"
    },
    "audio": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    text: 'وين طلبي؟ رقمه سبعة تسعة واحد اثنين',
    history: [{text: '<string>'}],
    variables: {customer_name: 'أحمد', branch: 'الملز'},
    audio: true
  })
};

fetch('https://app.voho.ai/v1/agents/{id}/reply', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.voho.ai/v1/agents/{id}/reply",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'text' => 'وين طلبي؟ رقمه سبعة تسعة واحد اثنين',
    'history' => [
        [
                'text' => '<string>'
        ]
    ],
    'variables' => [
        'customer_name' => 'أحمد',
        'branch' => 'الملز'
    ],
    'audio' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.voho.ai/v1/agents/{id}/reply"

	payload := strings.NewReader("{\n  \"text\": \"وين طلبي؟ رقمه سبعة تسعة واحد اثنين\",\n  \"history\": [\n    {\n      \"text\": \"<string>\"\n    }\n  ],\n  \"variables\": {\n    \"customer_name\": \"أحمد\",\n    \"branch\": \"الملز\"\n  },\n  \"audio\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.voho.ai/v1/agents/{id}/reply")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"وين طلبي؟ رقمه سبعة تسعة واحد اثنين\",\n  \"history\": [\n    {\n      \"text\": \"<string>\"\n    }\n  ],\n  \"variables\": {\n    \"customer_name\": \"أحمد\",\n    \"branch\": \"الملز\"\n  },\n  \"audio\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.voho.ai/v1/agents/{id}/reply")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"وين طلبي؟ رقمه سبعة تسعة واحد اثنين\",\n  \"history\": [\n    {\n      \"text\": \"<string>\"\n    }\n  ],\n  \"variables\": {\n    \"customer_name\": \"أحمد\",\n    \"branch\": \"الملز\"\n  },\n  \"audio\": true\n}"

response = http.request(request)
puts response.read_body

{
  "reply": "<string>",
  "greeting": "<string>",
  "audio": "<string>",
  "content_type": "audio/mpeg",
  "cost_cents": 123
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API token."
  }
}

{
  "error": {
    "code": "insufficient_credit",
    "message": "Your credit balance is exhausted. Top up to continue."
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

What the agent says next, given what the caller just said. This is the turn-based path: you hold the call, you decide when to speak, and Voho supplies the reply and the audio for it. Use it when the telephony is yours. If you want Voho to hold the line instead, see Telephony.

How a call is assembled

You send what the caller said and the turns so far. Only the last 20 turns are used, so trim rather than growing the array forever.

curl https://app.voho.ai/v1/agents/ag_7f2c19/reply \
  -H "Authorization: Bearer voho_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "وين طلبي؟ رقمه سبعة تسعة واحد اثنين",
    "history": [
      { "role": "agent", "text": "مرحباً بك، كيف أقدر أساعدك؟" }
    ],
    "variables": { "branch": "الملز" }
  }'

The response carries the reply as text and, unless you asked it not to, as base64 audio ready to play down the line.

{
  "reply": "طلبك خرج للتوصيل اليوم. أرسل لك رابط التتبع؟",
  "greeting": "مرحباً بك في فرع الملز، كيف أقدر أساعدك؟",
  "audio": "SUQzBAAAAAAA...",
  "content_type": "audio/mpeg",
  "cost_cents": 3
}

Variables

variables are per request, and that is the whole point of them: one agent, a different value on every call. Anything you send overrides the defaults stored on the agent, and the values are filled into both the instructions and the greeting.

object

String values, keyed by the variable name used in the agent’s instructions.

Skipping the audio

Set audio to false when you only want the text: a chat channel, a test harness, an evaluation run. The turn is still charged; the synthesis is not.

Cost

Two cents a turn, plus the speech of the reply at the agent’s model rate. Both are in cost_cents and in the X-Voho-Cost-Cents header.

A live call held by Voho is priced by the minute instead, because the line is open whether or not anyone is speaking.

Authorizations

Authorization

string

header

required

API token from the Voho console. Begins with voho_sk_live_.

Path Parameters

string

required

The agent's ID, from /v1/agents.

Body

application/json

text

string

required

What the caller said. Truncated at 4,000 characters.

Example:

"وين طلبي؟ رقمه سبعة تسعة واحد اثنين"

history

object[]

The conversation so far. Only the last 20 turns are used.

Show child attributes

variables

object

Values for this call. They override the agent's stored defaults, which is the point of them: one agent, a value per call.

Show child attributes

Example:

{
  "customer_name": "أحمد",
  "branch": "الملز"
}

audio

boolean

default:true

Set to false to get text only and skip the synthesis charge.

Response

The reply.

string

greeting

string

The agent's greeting with variables filled in, for the start of a call.

audio

string | null

The spoken reply, base64 encoded. Null when audio was false.

content_type

string | null

Example:

"audio/mpeg"

cost_cents

integer

What this call cost, in cents. Also returned as the X-Voho-Cost-Cents header.

Overview

Speech

Voices

Agents

Understanding

Text utilities

Speech

Voices

Text

Agents

Understanding

Get an agent's reply

How a call is assembled

Variables

Skipping the audio

Cost

Authorizations

Path Parameters

Body

Response

​How a call is assembled

​Variables

​Skipping the audio

​Cost

Authorizations

Path Parameters

Body

Response

How a call is assembled

Variables

Skipping the audio

Cost