AGNTDocs

Voice

Voice

Live voice sessions, call history, voice engines and phone line requests.

POST/voice/live/session

Create a live voice session

Creates a short-lived voice session between the user and one of their assistants, scoped to a chat or task. When you pass neither, a new chat is created. Connect your client to `websocketUrl` with `sessionToken`.

Request body

assistantIdstringDefaults to the assistant of the chat or task.
chatIdstring | null
taskIdstring | null

Responses

200Session
okboolean
providerstringVoice engine for this assistant.
sessionIdstringPass to POST /voice/live/cancel to cancel before connecting.
websocketUrlstringWhere the client connects.
sessionTokenstringSingle-use token for that connection.
inputSampleRateintegerMicrophone audio rate in Hz.
outputSampleRateintegerAssistant audio rate in Hz.
metadataobjectIds the session is bound to: accountId, userId, assistantId, chatId, taskId.
404call_context_not_found: the assistant, chat or task is not this user's.
409voice_engine_not_configured or voice_not_configured
429voice_session_rate_limited: too many sessions in a short time.

Request

curl 'https://api.agnt.ai/voice/live/session' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "assistantId": "6660c4a1f2e3b7d8a9c01234",
  "chatId": "6660c4a1f2e3b7d8a9c01234",
  "taskId": "6660c4a1f2e3b7d8a9c01234"
}'

Response

{
  "ok": true,
  "provider": "provider",
  "sessionId": "3f6c2a9e-8b41-4d7a-9c15-2e7b0d4a6f18",
  "websocketUrl": "wss://voice.agnt.ai/live"
}
POST/voice/live/cancel

Cancel a live voice session

Cancels a live voice session the user created that has not connected yet. Returns `404` with `invalid_session` when there is no such session.

Request body

sessionId reqstring

Responses

200Success
ok reqenumtrue
cancelled reqenumtrue
404Voice unavailable or invalid context
status reqinteger
error_codestring
error reqstring

Request

curl 'https://api.agnt.ai/voice/live/cancel' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "sessionId": "6660c4a1f2e3b7d8a9c01234"
}'

Response

{
  "ok": true,
  "cancelled": true
}
GET/voice/providers

List voice engines

Returns the voice engines configured for your app, each with its voices and default voice. `available` says whether an engine can take calls now.

Responses

200Voice catalog
ok reqboolean
providers reqobject[]
idstringVoice engine id (provider)
namestring
enabledboolean
availableboolean
defaultVoiceIdstring
voicesobject[]
voiceIdstring
namestring
genderenummalefemaleother
descriptionstring

Request

curl 'https://api.agnt.ai/voice/providers' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "providers": [
    {
      "id": "6660c4a1f2e3b7d8a9c01234",
      "name": "Ava",
      "enabled": true,
      "available": true
    }
  ]
}
GET/voice/calls

List calls

Returns the user's calls, newest first: calls placed for them and each call their assistant made on their tasks. Requires `X-User-Email`.

Query parameters

limitinteger

Responses

200Calls
okboolean
callsobject[]
sourceenumdirecttask
idstring
taskIdstringTask rows only
taskTitlestring | null
relationshipenumuser: a call with the user. internal: someone in the user's organization. third_party: anyone else.userinternalthird_party
targetobject | null
phoneNumberstring
displayNamestring
goalstring | null
statusstringdirect: calling, completed, failed, no_answer, voicemail; task: pending, preparing, calling, in_progress, completed, failed, needs_input
dispositionstring | null
startedAtstring | null
endedAtstring | null
durationSecondsnumber
resultSummarystring | null
transcriptstring | null
400missing_user: send X-User-Email

Request

curl 'https://api.agnt.ai/voice/calls' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "calls": [
    {
      "source": "direct",
      "id": "6660c4a1f2e3b7d8a9c01234",
      "taskId": "6660c4a1f2e3b7d8a9c01234",
      "taskTitle": "tasktitle"
    }
  ]
}
POST/phone-line-requests

Create a phone line request

Requests phone numbers for the user's primary assistant. When the numbers are ready, they appear on the assistant under `channels`.

Request body

requestedChannelsobjectEach defaults to false
imessageboolean
smsboolean
whatsappboolean
voiceboolean
notesstring

Responses

201Created
okboolean
requestobject
idstring
assistantstring | null
requestedChannelsobject
imessageboolean
smsboolean
whatsappboolean
voiceboolean
notesstring | null
statusenumpendingfulfilleddismissed
reviewedAtstring | null
dismissalReasonstring | null
createdAtstring
400The user has no assistant, or a request is pending
401No user on the call: send X-User-Email with an account key, or use a user-scoped key
statusinteger
error_codestring
errorstring

Request

curl 'https://api.agnt.ai/phone-line-requests' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
  "requestedChannels": {
    "imessage": true,
    "sms": true,
    "whatsapp": true,
    "voice": true
  },
  "notes": "notes"
}'

Response

{
  "ok": true,
  "request": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "assistant": "assistant",
    "requestedChannels": {
      "imessage": true,
      "sms": true,
      "whatsapp": true,
      "voice": true
    },
    "notes": "notes"
  }
}
GET/phone-line-requests/mine

Retrieve the latest phone line request

Returns the user's most recent phone line request for their primary assistant, or `request: null` when there is none.

Responses

200Latest request
okboolean
requestobject | null
idstring
assistantstring | null
requestedChannelsobject
imessageboolean
smsboolean
whatsappboolean
voiceboolean
notesstring | null
statusenumpendingfulfilleddismissed
reviewedAtstring | null
dismissalReasonstring | null
createdAtstring
401No user on the call: send X-User-Email with an account key, or use a user-scoped key
statusinteger
error_codestring
errorstring

Request

curl 'https://api.agnt.ai/phone-line-requests/mine' \
  -H "Authorization: Bearer ak_live_..." \
  -H "X-User-Email: [email protected]"

Response

{
  "ok": true,
  "request": {
    "id": "6660c4a1f2e3b7d8a9c01234",
    "assistant": "assistant",
    "requestedChannels": {
      "imessage": true,
      "sms": true,
      "whatsapp": true,
      "voice": true
    },
    "notes": "notes"
  }
}