prod - 20261103-155809 - acd260dde964f9fc12a4ec4d79828e2feffa7ef1

Voice API

Use the Voice API to connect incoming telephone calls to your application. For each call, your application chooses how it exchanges conversation content with Seamly: as text or as audio.

Seamly sends the same authenticated HTTP request to your application’s endpoint to set up the conversation for both integration modes. Your application responds with the exchange mode, the conversation settings required for that mode, and a secure WebSocket URL. Seamly then opens the WebSocket connection for the duration of the call.

Requirements

Your application must provide:

  • An HTTPS endpoint that accepts a POST request.
  • Validation of Seamly's X-Seamly-Signature request header. see HMAC signature for more information.
  • A secure WebSocket ( wss:// ) endpoint for each conversation.
  • A message handler that implements the WebSocket event sequences described in this guide.
  • Logic that sends the first conversational message after acknowledging the WebSocket connection (when using exchange mode Text-to-voice).

Exchange modes

Text-to-voice

Use Text-to-voice when your application controls the conversation using text messages. Your application receives transcribed caller messages and sends text responses. Seamly handles the telephone connection, STT, TTS, barge-in, and call lifecycle.

Voice-to-voice

Use Voice-to-voice when your application has its own voice-processing capabilities. Your application receives the caller’s audio and sends audio responses directly to Seamly. Your application handles voice processing and conversation logic, while Seamly handles the telephone connection.

Integration flow overview

  1. A caller calls a telephone number assigned to your Seamly project.
  2. Seamly sends an authenticated POST request to your conversation endpoint.
  3. Your application validates the request and selects the exchange mode for that call.
  4. Your application returns 201 Created with the required configuration and a secure WebSocket URL.
  5. Seamly opens the WebSocket connection.
  6. Seamly and your application exchange text or audio, depending on the selected mode.
  7. The WebSocket connection remains active until the call ends or is transferred.

The exchange mode can be selected separately for every incoming call.

Next, follow the implementation guide for your chosen exchange mode to get started: