Sign in

v2

latestOpenAPI 3.1.02026-07-313981108.2 KB
Calls

Create Call

This API will create a new call. The call will be initiated and the call details will be returned. Call will be outbound call from assistant to the user.

post/calls/v1/conversations

Request body

userNumberstring required

This is the phone number of the user.

assistantNumberstring required

This is the phone number of the assistant.

metadataobject

This is the metadata of the conversation. You can add any additional information here.

assistantIdstring

This is the ID of the assistant that will be used for the conversation. If you already have an assistant, you can use this field to specify the assistantId instead of giving all the assistant configuration in the assistant object.

Example request

{
  "userNumber": "+1234567890",
  "assistantNumber": "+1234567890",
  "metadata": {
    "key": "value"
  },
  "assistant": {
    "name": "My Assistant",
    "welcomeMessage": "Hello! How can I help you?",
    "welcomeMessageMode": "assistant-speaks-first",
    "assistantProvider": "openai",
    "assistantModel": "gpt-4o-mini",
    "assistantSystemPrompt": "You are AI assistant to help patients with their health care needs.",
    "assistantMaxTokens": 256,
    "assistantResponseSplitter": ",",
    "config": {
      "speech": {
        "stt": {
          "vendor": "microsoft"
        },
        "sttFallback": {
          "vendor": "microsoft"
        },
        "ttsData": [
          {
            "enabled": true,
            "vendor": "eleven-labs",
            "language": "en-US",
            "voice": "ZeK6O9RfGNGj0cJT2HoJ",
            "config": {
              "modelId": "eleven_multilingual_v2",
              "stability": 0.7,
              "similarityBoost": 0.85,
              "speakerBoost": true,
              "styleExaggeration": 0.5,
              "seed": 42,
              "speed": 1,
              "applyTextNormalization": true
            }
          }
        ]
      }
    },
    "backgroundSound": "enable",
    "backgroundSoundVolume": 50,
    "maxConsecutiveTtsFailures": 2,
    "recordingEnabled": true,
    "maxCallDuration": 900,
    "idleTimeout": 20,
    "maxIdleMessagesInSequence": 3,
    "userInterruptionAckPlan": {
      "phrases": [
        "Please hold on while I check your account.",
        "one moment please",
        "let me just check that for you"
      ]
    },
    "assistantToolIds": [],
    "assistantKnowledgeBaseIds": [],
    "endCallMessage": "Goodbye!",
    "endCallToolDescription": "Trigger the end call only when the user is done with the conversation.",
    "endCallPhrases": [
      "goodbye",
      "bye"
    ],
    "callForwardData": [
      {
        "phoneNumber": "+1234567890",
        "name": "call-forward-name",
        "onFailedMessage": "The call forward failed. Please try again later."
      }
    ],
    "holdMusicUrl": "https://www.soundjay.com/ambient/sounds/people-in-lounge-1.mp3",
    "warmTransferTimeout": 300,
    "assistantAnalysis": {
      "summary": {
        "maxTokens": 256,
        "prompt": "Generate a summary of the call.",
        "timeoutSeconds": 30
      },
      "successEvaluation": {
        "maxTokens": 256,
        "prompt": "Evaluate the success of the call.",
        "timeoutSeconds": 30
      },
      "structuredData": {
        "maxTokens": 256,
        "prompt": "Extract structured data from the call.",
        "timeoutSeconds": 30
      }
    },
    "assistantOverrides": {
      "welcomeMessage": "Hello, how can I help you today?",
      "welcomeMessageMode": "assistant-speaks-first",
      "recordingEnabled": true,
      "maxConsecutiveTtsFailures": 2,
      "holdMusicUrl": "https://www.soundjay.com/ambient/sounds/people-in-lounge-1.mp3",
      "warmTransferTimeout": 300,
      "recordingPath": "/recordings",
      "dynamicVariables": {
        "user_name": "John Doe"
      }
    },
    "assistantServer": {
      "timeoutSeconds": 20,
      "url": "https://api.example.com/v1/getUserDetails",
      "secret": "my-secret",
      "headers": {}
    },
    "persistHistory": {
      "retentionPeriod": 7
    }
  },
  "assistantId": "678a253ca6d866573043502e",
  "assistantOverrides": {
    "welcomeMessage": "Hello, how can I help you today?",
    "welcomeMessageMode": "assistant-speaks-first",
    "recordingEnabled": true,
    "maxConsecutiveTtsFailures": 2,
    "holdMusicUrl": "https://www.soundjay.com/ambient/sounds/people-in-lounge-1.mp3",
    "warmTransferTimeout": 300,
    "recordingPath": "/recordings",
    "dynamicVariables": {
      "user_name": "John Doe"
    }
  }
}

Response

Successful response

sidstring

Unique identifier of the call

Example response

{
  "sid": "a12f9c88-c155-461f-9771-4d240cdc9a04"
}