Skip to main content
POST
/
v1
/
calls
cURL
curl --request POST \
  --url https://api.langcall.com/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "full_ai",
  "to_number": "+1234567890",
  "instruction": "Get a home loan certificate and send it to [email protected]",
  "transfer_number": "+0987654321",
  "voice_id": "aura-asteria-en",
  "status_callback": "https://webhook.site/97f897b1-288d-4772-9a6e-11111"
}
'
{
  "type": "full_ai",
  "to_number": "+1234567890",
  "instruction": "Get a home loan certificate and send it to [email protected]",
  "id": "<string>",
  "created_at": "<string>",
  "direction": "inbound",
  "duration": 123,
  "conversations": [
    {
      "role": "assistant",
      "content": "<string>"
    }
  ],
  "transfer_number": "+0987654321",
  "voice_id": "aura-asteria-en",
  "status_callback": "https://webhook.site/97f897b1-288d-4772-9a6e-11111"
}

​
Voice ID

The voice ID is the identifier of the voice model to use for the call. You can refer to the below tables to find the voice ID for your preferred voice.

​
Low-latency and human-like AI voices

IDText
aura-asteria-enAsteria, American female
aura-athena-enAthena, British female
aura-luna-enLuna, American female
aura-stella-enStella, American female
aura-helios-enHelios, British male
aura-orion-enOrion, American male
aura-orpheus-enOrpheus, American male

​
Ultra-high quality AI voices

IDTextPreview
EXAVITQu4vr4xnSDxMaLSarah, American female, youngPreview
FGY2WhTYpPnrIDTdsKH5Laura, American female, youngPreview
IKne3meq5aSn9XLyUdCDCharlie, Australian male, middle-agedPreview
JBFqnCBsd6RMkjVDRZzbGeorge, British male, middle-agedPreview
N2lVS1w4EtoT3dr4eOWOCallum, Transatlantic male, middle-agedPreview
TX3LPaxmHKxFdv7VOQHJLiam, American male, youngPreview
XB0fDUnXU5powFXDhCwaCharlotte, Swedish female, youngPreview
Xb7hH8MSUJpSbSDYk0k2Alice, British female, middle-agedPreview
XrExE9yKIg1WjnnlVkGXMatilda, American female, middle-agedPreview
bIHbv24MWmeRgasZH58oWill, American male, youngPreview
cgSgspJ2msm6clMCkdW9Jessica, American female, youngPreview
cjVigY5qzO86Huf0OWalEric, American male, middle-agedPreview
iP95p4xoKVk53GoZ742BChris, American male, middle-agedPreview
nPczCjzI2devNBz1zQrbBrian, American male, middle-agedPreview
onwK4e9ZLuTAKqWW03F9Daniel, British male, middle-agedPreview
pFZP5JQG7iQjIQuC4BkuLily, British female, middle-agedPreview
pqHfZKP75CvOlQylNhV4Bill, American male, oldPreview

​
Status Callback

The status callback is a webhook URL that will be called when the call status is updated. The URL must be publicly accessible and accept a POST request with a JSON body. The status_callback parameter is optional. If you don’t specify it, the call will not be updated. If you specify it, the call will be updated with the following events:
EventDescription
initiatedThe AI call starts dialing.
ringingThe call starts ringing.
answeredThe call is answered. If this event is specified, LangCall will send an in-progress status.
completedThe call is completed, regardless of the termination status (which can be busy, cancelled, completed, failed, or no-answer).
LangCall will send a POST request to the URL with the following JSON body: 
"id": "ID123",
  "type": "full_ai",
  "to_number": "+1234567890",
  "instruction": "inform the user that he has a meeting tomorrow at 6pm",
  "transfer_number": null,
  "voice_id": "aura-asteria-en",
  "created_at": "2024-09-25T22:22:08.095646+00:00",
  "direction": "outbound",
  "duration": 1,
  "status": "completed",
  "status_callback": "https://webhook.site/123456789",
  "conversations": [{"role": "user", "content": "Hello"}, {"role": "assistant", "content": "Hi, this is Jason, I'm calling to let you know that you have a meeting tomorrow at 6pm."}]

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Data required to initiate an AI call

​
type
enum<string>
required

Type of the call

Available options:
full_ai,
transfer
Example:

"full_ai"

​
to_number
string
required

Number to call. Phone numbers should be formatted in E.164 format with a + and country code, for example: +16175551212.

Example:

"+1234567890"

​
instruction
string
required

Detailed instruction for the call

Example:

"Get a home loan certificate and send it to [email protected]"

​
transfer_number
string

Required if the call type is “transfer.” If you need to include an extension, separate the number and extension with a comma. For example: +0987654321,123.

Example:

"+0987654321"

​
voice_id
string

Voice ID to use for the call.

Example:

"aura-asteria-en"

​
status_callback
string | null

Webhook URL to be called when the call status is updated.

Example:

"https://webhook.site/97f897b1-288d-4772-9a6e-11111"

Response

call response

​
type
enum<string>
required

Type of the call

Available options:
full_ai,
transfer
Example:

"full_ai"

​
to_number
string
required

Number to call. Phone numbers should be formatted in E.164 format with a + and country code, for example: +16175551212.

Example:

"+1234567890"

​
instruction
string
required

Detailed instruction for the call

Example:

"Get a home loan certificate and send it to [email protected]"

​
id
string

Identification number of the call

​
created_at
string

Time when the call was started in ISO 8601 standard, e.g. 2024-09-25T22:22:08.095646+00:00

​
direction
enum<string>

Direction of the call: inbound or outbound

Available options:
inbound,
outbound
​
duration
number

Duration of the call in minutes

​
conversations
object[]

A list of messages comprising the phone conversation so far

​
transfer_number
string

Required if the call type is “transfer.” If you need to include an extension, separate the number and extension with a comma. For example: +0987654321,123.

Example:

"+0987654321"

​
voice_id
string

Voice ID to use for the call.

Example:

"aura-asteria-en"

​
status_callback
string | null

Webhook URL to be called when the call status is updated.

Example:

"https://webhook.site/97f897b1-288d-4772-9a6e-11111"