Skip to main content
POST
/
calls
/
v1
/
conversations
Create Call
curl --request POST \
  --url https://api-qa.interactly.ai/calls/v1/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userNumber": "+1234567890",
  "assistantNumber": "+1234567890",
  "metadata": {
    "key": "value"
  },
  "assistant": {
    "name": "My Assistant",
    "welcomeMessage": "Hello! How can I help you?",
    "welcomeMessageMode": "assistant-speaks-first",
    "welcomeMessageInterruptionsEnabled": false,
    "assistantProvider": "openai",
    "assistantModel": "gpt-4o-mini",
    "assistantLLMUrl": "<string>",
    "assistantSystemPrompt": "You are AI assistant to help patients with their health care needs.",
    "assistantTemperature": 0,
    "assistantMaxTokens": 256,
    "assistantResponseSplitter": ",",
    "config": {
      "speech": {
        "stt": {
          "vendor": "microsoft",
          "languages": "en-US"
        },
        "sttFallback": {
          "enabled": true,
          "vendor": "microsoft",
          "languages": "en-US"
        },
        "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
            }
          }
        ]
      }
    },
    "hints": [
      "<string>"
    ],
    "backgroundSound": "enable",
    "backgroundSoundVolume": 50,
    "ttsCacheEnabled": false,
    "ttsAudioCacheScope": "assistant",
    "assistantBackchannelingEnabled": false,
    "dtmfInputEnabled": false,
    "maxCallDuration": 900,
    "idleTimeout": 20,
    "maxIdleMessagesInSequence": 3,
    "startSpeakingOptions": {
      "waitSeconds": 0,
      "smartEndpointing": "Interactly",
      "onPunctuationSeconds": 0,
      "onNoPunctuationSeconds": 0,
      "onNumberSeconds": 0,
      "LiveKitBaseValue": 100,
      "LiveKitScaleValue": 1000
    },
    "stopSpeakingOptions": {
      "numberOfWords": 3,
      "voiceSeconds": 0
    },
    "userInterruptionAckPlan": {
      "enabled": true,
      "count": 2,
      "words": 4,
      "phrases": [
        "Please hold on while I check your account.",
        "one moment please",
        "let me just check that for you"
      ]
    },
    "assistantToolIds": [],
    "assistantPredefinedTools": {
      "knowledgeBase": false,
      "endCall": false,
      "appointment": false,
      "volumeControl": false,
      "waitList": false,
      "callForward": false
    },
    "assistantType": "single_prompt",
    "assistantKnowledgeBaseIds": [],
    "endCallMessage": "Goodbye!",
    "endCallToolDescription": "Trigger the end call only when the user is done with the conversation.",
    "endCallPhrases": [
      "goodbye",
      "bye"
    ],
    "callForwardData": {
      "phoneNumber": "+1234567890",
      "extension": "",
      "name": "call-forward-name"
    },
    "assistantAnalysis": {
      "summary": {
        "enabled": false,
        "prompt": "Generate a summary of the call.",
        "timeoutSeconds": 30
      },
      "successEvaluation": {
        "enabled": false,
        "prompt": "Evaluate the success of the call.",
        "rubric": "NumericScale",
        "timeoutSeconds": 30
      },
      "structuredData": {
        "enabled": false,
        "prompt": "Extract structured data from the call.",
        "timeoutSeconds": 30,
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "This is the name of the user.",
              "example": "John Doe"
            },
            "dob": {
              "type": "string",
              "format": "date",
              "description": "This is the date of birth of the user.",
              "example": "1990-03-08"
            }
          }
        }
      }
    },
    "assistantOverrides": {
      "welcomeMessage": "Hello, how can I help you today?",
      "welcomeMessageMode": "assistant-speaks-first",
      "welcomeMessageInterruptionsEnabled": false,
      "recordingEnabled": true,
      "recordingPath": "/recordings",
      "dynamicVariables": {
        "user_name": "John Doe"
      }
    },
    "assistantServer": {
      "url": "https://api.example.com/v1/getUserDetails",
      "timeoutSeconds": 20,
      "secret": "my-secret",
      "headers": {},
      "enabled": false,
      "messages": [
        "status-update",
        "conversation-update",
        "hang",
        "end-of-call-report",
        "error"
      ]
    },
    "assistantOutcome": [
      {
        "type": "<string>",
        "field": "<string>"
      }
    ],
    "smsConfiguration": {
      "enabled": true,
      "sameAsAssistant": true,
      "smsPrompt": "<string>"
    },
    "persistHistory": {
      "enabled": true,
      "call": true,
      "sms": true,
      "retentionPeriod": 7
    }
  },
  "assistantId": "678a253ca6d866573043502e",
  "assistantOverrides": {
    "welcomeMessage": "Hello, how can I help you today?",
    "welcomeMessageMode": "assistant-speaks-first",
    "welcomeMessageInterruptionsEnabled": false,
    "recordingEnabled": true,
    "recordingPath": "/recordings",
    "dynamicVariables": {
      "user_name": "John Doe"
    }
  }
}
'
{
  "sid": "a12f9c88-c155-461f-9771-4d240cdc9a04"
}

Authorizations

​
Authorization
string
header
required

Retrieve your API Key from Dashboard API Keys Section.

Body

application/json
​
userNumber
string
required

This is the phone number of the user.

Example:

"+1234567890"

​
assistantNumber
string
required

This is the phone number of the assistant.

Example:

"+1234567890"

​
metadata
object

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

Example:
{ "key": "value" }
​
assistant
object

This is the assistant that will be used for the call. To use an existing assistant, use assistantId instead.

If both assistant and assistantId are provided, only assistant will be used for this conversation. If both assistant and assistantId are not provided, the default assistant that is attached to phone number will be used for the call.

​
assistantId
string

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:

"678a253ca6d866573043502e"

​
assistantOverrides
object

This is where you can override the default behavior of the assistant.

Response

200 - application/json

Successful response

​
sid
string

Unique identifier of the call

Example:

"a12f9c88-c155-461f-9771-4d240cdc9a04"