Stream Calls

Create Stream Token

The first step of a stream call: creates the call and returns the WebSocket url, a single-use token valid 60 seconds, and the audio format. Requires the pearls:stream scope.

Then open url?token=<token> within 60 seconds: Stream WebSocket describes the connection, the audio and the events.

Errors

A 400 lists its messages in errors.validation. Several callData problems are reported together.

Message in `errors.validation`	Cause
`Pearl not found`	`pearlId` is not a valid id, none of your Pearls has it, or the Pearl was deleted.
`Stream calls are available for voice Pearls only.`	Your Pearl is a text Pearl.
`The Pearl is not active.`	Your Pearl is paused. Activate it with Set Activity State.
`endUserId must not exceed 200 characters.`	`endUserId` is longer than 200 characters.
`audioFormat 'X' is not supported. Valid: ulaw_8000, pcm_24000, opus_8000, opus_24000.`	`audioFormat` is not one of the four formats.
`callData key cannot be null or whitespace.` `callData key 'K' must not exceed 40 characters.` `callData key 'K' contains invalid characters. Only letters, digits, underscores (_) and hyphens (-) are allowed.` `callData value for key 'K' must not exceed 200 characters.`	A `callData` entry is invalid.
`Missing pre-call variables: firstName, orderId.`	Required `callData` entries are absent or blank.
`Call cannot be completed: The client has no remaining credits. Please recharge to continue.`	The account has no credits left.
`Call cannot be completed: Account Suspended! Please contact support.`	The account is suspended.
`The Pearl has no flow yet.` `Invalid Conversation Flow`	Your Pearl has no usable flow.
`The Pearl has no inbound settings.` `The Pearl has no outbound settings.`	Your Pearl’s direction settings are missing.
`No agent is available for this Pearl right now, try again later.`	All your Pearl’s agents are busy, phone calls and stream calls together, or it has none. Retry later.
`Could not start the call.`	An internal failure. The agent it reserved stays taken for about 90 seconds, so a retry may get `No agent is available…` until then.

Malformed JSON or a field of the wrong type (a number as audioFormat, for example) get the standard 400, with the error under the field name.

Agents and cancelling

A successful create reserves one of your Pearl’s agents until the call ends. To cancel the call, before or during it, use Hang Up Call: a token that was never used is then refused, and its agent is freed. A token that is never used and never cancelled keeps the agent for about 90 seconds, and costs nothing.

A create refused with No agent is available… or Could not start the call. still appears in the call history, as a call that never started.

POST

Pearl

{pearlId}

Stream

Token

Create Stream Token

curl --request POST \
  --url https://api.nlpearl.ai/v2/Pearl/{pearlId}/Stream/Token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endUserId": "crm-77812",
  "callData": {
    "firstName": "Dana",
    "orderId": "A-1234"
  },
  "audioFormat": "opus_24000"
}
'

import requests

url = "https://api.nlpearl.ai/v2/Pearl/{pearlId}/Stream/Token"

payload = {
    "endUserId": "crm-77812",
    "callData": {
        "firstName": "Dana",
        "orderId": "A-1234"
    },
    "audioFormat": "opus_24000"
}
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({
    endUserId: 'crm-77812',
    callData: {firstName: 'Dana', orderId: 'A-1234'},
    audioFormat: 'opus_24000'
  })
};

fetch('https://api.nlpearl.ai/v2/Pearl/{pearlId}/Stream/Token', 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://api.nlpearl.ai/v2/Pearl/{pearlId}/Stream/Token",
  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([
    'endUserId' => 'crm-77812',
    'callData' => [
        'firstName' => 'Dana',
        'orderId' => 'A-1234'
    ],
    'audioFormat' => 'opus_24000'
  ]),
  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://api.nlpearl.ai/v2/Pearl/{pearlId}/Stream/Token"

	payload := strings.NewReader("{\n  \"endUserId\": \"crm-77812\",\n  \"callData\": {\n    \"firstName\": \"Dana\",\n    \"orderId\": \"A-1234\"\n  },\n  \"audioFormat\": \"opus_24000\"\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://api.nlpearl.ai/v2/Pearl/{pearlId}/Stream/Token")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"endUserId\": \"crm-77812\",\n  \"callData\": {\n    \"firstName\": \"Dana\",\n    \"orderId\": \"A-1234\"\n  },\n  \"audioFormat\": \"opus_24000\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nlpearl.ai/v2/Pearl/{pearlId}/Stream/Token")

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  \"endUserId\": \"crm-77812\",\n  \"callData\": {\n    \"firstName\": \"Dana\",\n    \"orderId\": \"A-1234\"\n  },\n  \"audioFormat\": \"opus_24000\"\n}"

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

{
  "callId": "6720f3c1a8b4e5d6f7a8b9c0",
  "url": "wss://agents.nlpearl.ai/Stream/WebSocket",
  "token": "wst_kX9vQ2...",
  "expiresAt": "2026-10-28T09:01:00Z",
  "audio": {
    "encoding": "opus",
    "sampleRate": 24000,
    "channels": 1,
    "frameMs": 20
  }
}

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "validation": [
      "Missing pre-call variables: firstName."
    ]
  }
}

Authorizations

Authorization

string

header

required

Specify the authorization token.

For more information, check out the Authorization Guide.

Path Parameters

pearlId

string

required

Your Pearl's id. It must be an active voice Pearl. Find it on your Pearl's overview page, in the Settings popover.

Body

Represents the data required to create a stream token.

endUserId

string | null

Your own id for the person on the call, such as a customer id, an e-mail or a phone number, up to 200 characters. A stream call has no phone number, so this takes its place: in the call history, in your Pearl's memory, and in the flow's Phone Number variable. Send the same value for the same person every time, and never one value for different people.

         Optional. Absent, `null` or blank, the call has no end user: the Phone Number variable is empty, and the Pearl neither recalls an earlier call nor remembers this one.

Maximum string length: 200

callData

object | null

The flow's pre-call variables, by variable name: the same dictionary as a phone call's callData.

Required entries: every variable used in the opening sentence, and every input of a pre-call API, present and not blank. Other variables are optional.

Keys are letters (any script), digits, _ and -, up to 40 characters. Values are strings, up to 200 characters.

Show child attributes

audioFormat

string | null

default:ulaw_8000

The audio format of the call, the same in both directions. We recommend opus_24000: HD for far less bandwidth.

opus_24000: Opus at 24 kHz, HD.
opus_8000: Opus at 8 kHz, phone quality.
ulaw_8000: 8 kHz G.711 μ-law, phone quality.
pcm_24000: 24 kHz 16-bit little-endian PCM, HD.

Case-insensitive. Absent, null or empty means ulaw_8000, and any other value is refused.

Response

The call was created: connect with the token before it expires.

Represents what your server needs to connect a stream call.

callId

string | null

The call's id: the same id as in Get Call, the call list and the webhooks.

url

string | null

The WebSocket URL. Open it with the token: url?token=<token>. Always use the returned value rather than a fixed address.

token

string | null

The single-use token for the connection, starting with wst_. It is valid for 60 seconds and is consumed by the first successful connection. Treat it as a secret. From a server you can send it in the Authorization: Bearer header instead of the query.

expiresAt

string<date-time>

When the token stops being accepted, in ISO 8601 UTC: creation plus 60 seconds.

audio

object | null

The format of every audio frame, in both directions.

Show child attributes

Create Stream Token

curl --request POST \
  --url https://api.nlpearl.ai/v2/Pearl/{pearlId}/Stream/Token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endUserId": "crm-77812",
  "callData": {
    "firstName": "Dana",
    "orderId": "A-1234"
  },
  "audioFormat": "opus_24000"
}
'

import requests

url = "https://api.nlpearl.ai/v2/Pearl/{pearlId}/Stream/Token"

payload = {
    "endUserId": "crm-77812",
    "callData": {
        "firstName": "Dana",
        "orderId": "A-1234"
    },
    "audioFormat": "opus_24000"
}
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({
    endUserId: 'crm-77812',
    callData: {firstName: 'Dana', orderId: 'A-1234'},
    audioFormat: 'opus_24000'
  })
};

fetch('https://api.nlpearl.ai/v2/Pearl/{pearlId}/Stream/Token', 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://api.nlpearl.ai/v2/Pearl/{pearlId}/Stream/Token",
  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([
    'endUserId' => 'crm-77812',
    'callData' => [
        'firstName' => 'Dana',
        'orderId' => 'A-1234'
    ],
    'audioFormat' => 'opus_24000'
  ]),
  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://api.nlpearl.ai/v2/Pearl/{pearlId}/Stream/Token"

	payload := strings.NewReader("{\n  \"endUserId\": \"crm-77812\",\n  \"callData\": {\n    \"firstName\": \"Dana\",\n    \"orderId\": \"A-1234\"\n  },\n  \"audioFormat\": \"opus_24000\"\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://api.nlpearl.ai/v2/Pearl/{pearlId}/Stream/Token")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"endUserId\": \"crm-77812\",\n  \"callData\": {\n    \"firstName\": \"Dana\",\n    \"orderId\": \"A-1234\"\n  },\n  \"audioFormat\": \"opus_24000\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nlpearl.ai/v2/Pearl/{pearlId}/Stream/Token")

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  \"endUserId\": \"crm-77812\",\n  \"callData\": {\n    \"firstName\": \"Dana\",\n    \"orderId\": \"A-1234\"\n  },\n  \"audioFormat\": \"opus_24000\"\n}"

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

{
  "callId": "6720f3c1a8b4e5d6f7a8b9c0",
  "url": "wss://agents.nlpearl.ai/Stream/WebSocket",
  "token": "wst_kX9vQ2...",
  "expiresAt": "2026-10-28T09:01:00Z",
  "audio": {
    "encoding": "opus",
    "sampleRate": 24000,
    "channels": 1,
    "frameMs": 20
  }
}

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "validation": [
      "Missing pre-call variables: firstName."
    ]
  }
}

Getting Started

API V2

API V1

Create Stream Token

Errors

Agents and cancelling

Authorizations

Path Parameters

Body

Response