Voice

Voice calls

Place and receive phone calls, speak text in 100+ languages, play audio and hang up, all driven by events sent to your webhook as the call progresses.

How a call works

01You place a call (or someone calls your number). The API answers at once with a call id.
02As the call progresses, Pulsr sends events to your webhook: CALL_RINGING, CALL_ESTABLISHED, CALL_FINISHED…
03Your handler reacts to each event with actions on the call: say, play, answer, hangup.

One-time setup

Calls belong to a calls configuration, and events reach you through an event subscription on that configuration. Create both once, from a script or the dashboard.

setup-voice.ts

// 1. A calls configuration groups your calls and their event settingsawait pulsr("POST", "/calls/1/configurations", {  id: "support-line",  name: "Support line",});// 2. Subscribe your webhook to the events you want for that configurationawait pulsr("POST", "/subscriptions/1/subscription/VOICE_VIDEO", {  subscriptionId: "support-line-events",  events: [    "CALL_RECEIVED",    "CALL_ESTABLISHED",    "SAY_FINISHED",    "CALL_FINISHED",    "CALL_FAILED",  ],  criteria: [{ callsConfigurationId: "support-line" }],  profile: {    profileId: "support-line-webhook",    webhook: { notifyUrl: "https://yourapp.com/webhooks/calls?token=…" },  },});

Place a call

POST/calls/1/calls

place-call.ts

const call = await pulsr("POST", "/calls/1/calls", {  endpoint: { type: "PHONE", phoneNumber: "33639985678" },  from: "33199004242",  callsConfigurationId: "support-line",  connectTimeout: 30, // seconds of ringing before giving up  maxDuration: 600,  machineDetection: { enabled: true },  customData: { ticketId: "T-1042" },});console.log(call.id, call.state); // ... CALLING

Response · 201 Created

{  "id": "d8d84155-3831-43fb-91c9-10b5a8d628a0",  "endpoint": { "type": "PHONE", "phoneNumber": "33639985678" },  "from": "33199004242",  "to": "33639985678",  "direction": "OUTBOUND",  "state": "CALLING",  "callsConfigurationId": "support-line",  "customData": { "ticketId": "T-1042" }}

Request body

endpointobjectRequired: Who to call. { type: "PHONE", phoneNumber } for a phone; WEBRTC and SIP endpoints are also supported.
fromstring: The caller ID, one of your voice numbers.
callsConfigurationIdstringRequired: The configuration the call belongs to.
connectTimeoutinteger: Seconds to ring before giving up.
maxDurationinteger: Seconds after which the call is ended.
machineDetection.enabledboolean: Detect answering machines. The result arrives as a MACHINE_DETECTION_FINISHED event.
recording.recordingTypestring: AUDIO or AUDIO_AND_VIDEO to record the call.
customDataobject: Your own key-value pairs, returned in call events.

Get the current state of a call at any time with GET /calls/1/calls/{callId}. You can place up to 6 calls per second.

Each event is a JSON object with a type, the callId, a timestamp and properties. Ringing and established events include the full call; finished and failed events include a callLog with the duration and the hang-up reason.

Event · CALL_ESTABLISHED

{  "type": "CALL_ESTABLISHED",  "callId": "d8d84155-3831-43fb-91c9-10b5a8d628a0",  "timestamp": "2026-10-19T09:30:12.000+0000",  "callsConfigurationId": "support-line",  "properties": {    "call": {      "id": "d8d84155-3831-43fb-91c9-10b5a8d628a0",      "from": "33199004242",      "to": "33639985678",      "direction": "OUTBOUND",      "state": "ESTABLISHED",      "startTime": "2026-10-19T09:30:04.000+0000",      "answerTime": "2026-10-19T09:30:12.000+0000",      "customData": { "ticketId": "T-1042" }    }  }}

Event	When
`CALL_RECEIVED`	Someone is calling one of your numbers.
`CALL_RINGING`	The other side is ringing.
`CALL_ESTABLISHED`	The call was answered.
`SAY_FINISHED`, `PLAY_FINISHED`	Speech or audio ended, with any keys pressed.
`DTMF_CAPTURED`	Keys pressed on the keypad were collected.
`MACHINE_DETECTION_FINISHED`	Answering machine detection has a result.
`CALL_FINISHED`	The call ended normally.
`CALL_FAILED`	The call could not be connected (busy, no answer, rejected…).

Speak, play and hang up

Actions run on a live call and return { "status": "PENDING" } right away; their end comes as an event. say accepts plain text or SSML and a language code, play takes an audio URL or an uploaded file.

call-actions.ts

const path = `/calls/1/calls/${callId}`;// Text-to-speech, stopped early if the person presses #await pulsr("POST", `${path}/say`, {  text: "Press 1 to confirm your appointment, or 2 to cancel it.",  language: "en",  speechRate: 1,  preferences: { voiceGender: "FEMALE" },  stopOn: { type: "DTMF", terminator: "#" },});// Play an audio file from a URLawait pulsr("POST", `${path}/play`, {  content: { type: "URL", fileUrl: "https://yourapp.com/hold.wav" },  loopCount: 3,});// Hang upawait pulsr("POST", `${path}/hangup`, {});

Answer incoming calls

When someone calls your number you receive CALL_RECEIVED. Answer it, then drive the call like an outbound one. This handler answers, speaks a message, then hangs up when the message ends:

app/webhooks/calls/route.ts

import { pulsr } from "@/lib/client";export async function POST(req: Request) {  // Check the token first, see the Webhooks guide  const event = await req.json(); // one event per request  const path = `/calls/1/calls/${event.callId}`;  switch (event.type) {    case "CALL_RECEIVED":      await pulsr("POST", `${path}/answer`, {});      break;    case "CALL_ESTABLISHED":      await pulsr("POST", `${path}/say`, {        text: "Hello, this is YourApp support. Your ticket is resolved. Goodbye!",        language: "en",      });      break;    case "SAY_FINISHED":      await pulsr("POST", `${path}/hangup`, {});      break;    case "CALL_FINISHED":    case "CALL_FAILED":      await calls.save(event.callId, event.properties.callLog);      break;  }  return new Response(null, { status: 200 });}

One-time setup

Calls belong to a calls configuration, and events reach you through an event subscription on that configuration. Create both once, from a script or the dashboard.

setup-voice.ts

// 1. A calls configuration groups your calls and their event settingsawait pulsr("POST", "/calls/1/configurations", {  id: "support-line",  name: "Support line",});// 2. Subscribe your webhook to the events you want for that configurationawait pulsr("POST", "/subscriptions/1/subscription/VOICE_VIDEO", {  subscriptionId: "support-line-events",  events: [    "CALL_RECEIVED",    "CALL_ESTABLISHED",    "SAY_FINISHED",    "CALL_FINISHED",    "CALL_FAILED",  ],  criteria: [{ callsConfigurationId: "support-line" }],  profile: {    profileId: "support-line-webhook",    webhook: { notifyUrl: "https://yourapp.com/webhooks/calls?token=…" },  },});

Place a call

POST/calls/1/calls

place-call.ts

const call = await pulsr("POST", "/calls/1/calls", {  endpoint: { type: "PHONE", phoneNumber: "33639985678" },  from: "33199004242",  callsConfigurationId: "support-line",  connectTimeout: 30, // seconds of ringing before giving up  maxDuration: 600,  machineDetection: { enabled: true },  customData: { ticketId: "T-1042" },});console.log(call.id, call.state); // ... CALLING

Response · 201 Created

{  "id": "d8d84155-3831-43fb-91c9-10b5a8d628a0",  "endpoint": { "type": "PHONE", "phoneNumber": "33639985678" },  "from": "33199004242",  "to": "33639985678",  "direction": "OUTBOUND",  "state": "CALLING",  "callsConfigurationId": "support-line",  "customData": { "ticketId": "T-1042" }}

Request body

endpointobjectRequired: Who to call. { type: "PHONE", phoneNumber } for a phone; WEBRTC and SIP endpoints are also supported.
fromstring: The caller ID, one of your voice numbers.
callsConfigurationIdstringRequired: The configuration the call belongs to.
connectTimeoutinteger: Seconds to ring before giving up.
maxDurationinteger: Seconds after which the call is ended.
machineDetection.enabledboolean: Detect answering machines. The result arrives as a MACHINE_DETECTION_FINISHED event.
recording.recordingTypestring: AUDIO or AUDIO_AND_VIDEO to record the call.
customDataobject: Your own key-value pairs, returned in call events.

Get the current state of a call at any time with GET /calls/1/calls/{callId}. You can place up to 6 calls per second.

Call events

Event · CALL_ESTABLISHED

{  "type": "CALL_ESTABLISHED",  "callId": "d8d84155-3831-43fb-91c9-10b5a8d628a0",  "timestamp": "2026-10-19T09:30:12.000+0000",  "callsConfigurationId": "support-line",  "properties": {    "call": {      "id": "d8d84155-3831-43fb-91c9-10b5a8d628a0",      "from": "33199004242",      "to": "33639985678",      "direction": "OUTBOUND",      "state": "ESTABLISHED",      "startTime": "2026-10-19T09:30:04.000+0000",      "answerTime": "2026-10-19T09:30:12.000+0000",      "customData": { "ticketId": "T-1042" }    }  }}

Event	When
`CALL_RECEIVED`	Someone is calling one of your numbers.
`CALL_RINGING`	The other side is ringing.
`CALL_ESTABLISHED`	The call was answered.
`SAY_FINISHED`, `PLAY_FINISHED`	Speech or audio ended, with any keys pressed.
`DTMF_CAPTURED`	Keys pressed on the keypad were collected.
`MACHINE_DETECTION_FINISHED`	Answering machine detection has a result.
`CALL_FINISHED`	The call ended normally.
`CALL_FAILED`	The call could not be connected (busy, no answer, rejected…).

Speak, play and hang up

call-actions.ts

const path = `/calls/1/calls/${callId}`;// Text-to-speech, stopped early if the person presses #await pulsr("POST", `${path}/say`, {  text: "Press 1 to confirm your appointment, or 2 to cancel it.",  language: "en",  speechRate: 1,  preferences: { voiceGender: "FEMALE" },  stopOn: { type: "DTMF", terminator: "#" },});// Play an audio file from a URLawait pulsr("POST", `${path}/play`, {  content: { type: "URL", fileUrl: "https://yourapp.com/hold.wav" },  loopCount: 3,});// Hang upawait pulsr("POST", `${path}/hangup`, {});

Answer incoming calls

When someone calls your number you receive CALL_RECEIVED. Answer it, then drive the call like an outbound one. This handler answers, speaks a message, then hangs up when the message ends:

app/webhooks/calls/route.ts

import { pulsr } from "@/lib/client";export async function POST(req: Request) {  // Check the token first, see the Webhooks guide  const event = await req.json(); // one event per request  const path = `/calls/1/calls/${event.callId}`;  switch (event.type) {    case "CALL_RECEIVED":      await pulsr("POST", `${path}/answer`, {});      break;    case "CALL_ESTABLISHED":      await pulsr("POST", `${path}/say`, {        text: "Hello, this is YourApp support. Your ticket is resolved. Goodbye!",        language: "en",      });      break;    case "SAY_FINISHED":      await pulsr("POST", `${path}/hangup`, {});      break;    case "CALL_FINISHED":    case "CALL_FAILED":      await calls.save(event.callId, event.properties.callLog);      break;  }  return new Response(null, { status: 200 });}