Voix

Appels vocaux

Passez et recevez des appels, lisez du texte dans plus de 100 langues, diffusez de l’audio et raccrochez, le tout piloté par les événements envoyés à votre webhook au fil de l’appel.

Le déroulé d’un appel

01Vous passez un appel (ou quelqu’un appelle votre numéro). L’API répond aussitôt avec l’id de l’appel.
02Au fil de l’appel, Pulsr envoie des événements à votre webhook : CALL_RINGING, CALL_ESTABLISHED, CALL_FINISHED…
03Votre handler réagit à chaque événement par des actions sur l’appel : say, play, answer, hangup.

Les appels appartiennent à une configuration d’appels, et les événements vous parviennent via un abonnement aux événements sur cette configuration. Créez les deux une fois, par script ou depuis le tableau de bord.

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=…" },  },});

Passer un appel

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

Réponse · 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" }}

Corps de la requête

endpointobjectObligatoire: Qui appeler. { type: "PHONE", phoneNumber } pour un téléphone ; les endpoints WEBRTC et SIP sont aussi gérés.
fromstring: Le numéro présenté, l’un de vos numéros vocaux.
callsConfigurationIdstringObligatoire: La configuration à laquelle appartient l’appel.
connectTimeoutinteger: Secondes de sonnerie avant abandon.
maxDurationinteger: Durée en secondes au bout de laquelle l’appel est coupé.
machineDetection.enabledboolean: Détecte les répondeurs. Le résultat arrive dans un événement MACHINE_DETECTION_FINISHED.
recording.recordingTypestring: AUDIO ou AUDIO_AND_VIDEO pour enregistrer l’appel.
customDataobject: Vos propres paires clé-valeur, renvoyées dans les événements.

Consultez l’état d’un appel à tout moment avec GET /calls/1/calls/{callId}. Vous pouvez passer jusqu’à 6 appels par seconde.

Événements d’appel

Chaque événement est un objet JSON avec un type, le callId, un timestamp et des properties. Les événements de sonnerie et de prise d’appel contiennent l’appel complet ; les événements de fin et d’échec contiennent un callLog avec la durée et la raison du raccrochage.

Événement · 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" }    }  }}

Événement	Quand
`CALL_RECEIVED`	Quelqu’un appelle l’un de vos numéros.
`CALL_RINGING`	Ça sonne de l’autre côté.
`CALL_ESTABLISHED`	L’appel a été décroché.
`SAY_FINISHED`, `PLAY_FINISHED`	La lecture du texte ou de l’audio est terminée, avec les touches pressées.
`DTMF_CAPTURED`	Les touches pressées sur le clavier ont été collectées.
`MACHINE_DETECTION_FINISHED`	La détection de répondeur a un résultat.
`CALL_FINISHED`	L’appel s’est terminé normalement.
`CALL_FAILED`	L’appel n’a pas pu aboutir (occupé, pas de réponse, refusé…).

Parler, diffuser, raccrocher

Les actions s’exécutent sur un appel en cours et répondent aussitôt { "status": "PENDING" } ; leur fin arrive sous forme d’événement. say accepte du texte brut ou du SSML et un code language, play prend une URL audio ou un fichier téléversé.

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`, {});

Répondre aux appels entrants

Quand quelqu’un appelle votre numéro, vous recevez CALL_RECEIVED. Décrochez, puis pilotez l’appel comme un appel sortant. Ce handler décroche, lit un message, puis raccroche à la fin du message :

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 });}

Le déroulé d’un appel

01Vous passez un appel (ou quelqu’un appelle votre numéro). L’API répond aussitôt avec l’id de l’appel.
02Au fil de l’appel, Pulsr envoie des événements à votre webhook : CALL_RINGING, CALL_ESTABLISHED, CALL_FINISHED…
03Votre handler réagit à chaque événement par des actions sur l’appel : say, play, answer, hangup.

Configuration initiale

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=…" },  },});

Passer un appel

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

Réponse · 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" }}

Corps de la requête

endpointobjectObligatoire: Qui appeler. { type: "PHONE", phoneNumber } pour un téléphone ; les endpoints WEBRTC et SIP sont aussi gérés.
fromstring: Le numéro présenté, l’un de vos numéros vocaux.
callsConfigurationIdstringObligatoire: La configuration à laquelle appartient l’appel.
connectTimeoutinteger: Secondes de sonnerie avant abandon.
maxDurationinteger: Durée en secondes au bout de laquelle l’appel est coupé.
machineDetection.enabledboolean: Détecte les répondeurs. Le résultat arrive dans un événement MACHINE_DETECTION_FINISHED.
recording.recordingTypestring: AUDIO ou AUDIO_AND_VIDEO pour enregistrer l’appel.
customDataobject: Vos propres paires clé-valeur, renvoyées dans les événements.

Consultez l’état d’un appel à tout moment avec GET /calls/1/calls/{callId}. Vous pouvez passer jusqu’à 6 appels par seconde.

Événements d’appel

Événement · 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" }    }  }}

Événement	Quand
`CALL_RECEIVED`	Quelqu’un appelle l’un de vos numéros.
`CALL_RINGING`	Ça sonne de l’autre côté.
`CALL_ESTABLISHED`	L’appel a été décroché.
`SAY_FINISHED`, `PLAY_FINISHED`	La lecture du texte ou de l’audio est terminée, avec les touches pressées.
`DTMF_CAPTURED`	Les touches pressées sur le clavier ont été collectées.
`MACHINE_DETECTION_FINISHED`	La détection de répondeur a un résultat.
`CALL_FINISHED`	L’appel s’est terminé normalement.
`CALL_FAILED`	L’appel n’a pas pu aboutir (occupé, pas de réponse, refusé…).

Parler, diffuser, raccrocher

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`, {});

Répondre aux appels entrants

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 });}