Connect Call

Authorizations

Authorization

string

header

required

Retrieve your API Key from Dashboard API Keys Section.

Body

application/json

direction

enum<string>

default:outbound

required

This is the direction of the conversation.

Inbound - The conversation is initiated by the user. Outbound - The conversation is initiated by the assistant.

Available options:

inbound,

outbound

Example:

"outbound"

phoneNumberId

string

required

Unique phone number ID. This is the phone number that will be used to make the call.

Example:

"5f7b1b1b1b1b1b1b1b1b1b1b"

customer

object

required

This is the customer object. It contains all the information about the customer.

Show child attributes

customer.number

string

This is the number of the customer.

customer.name

string

This is the name of the customer. This is just for your own reference.

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.

Show child attributes

assistant.name

string

This is the name of the assistant.

Example:

"My Assistant"

assistant.welcomeMessage

string

default:hi

This is the welcome message of the assistant.

Example:

"Hello! How can I help you?"

assistant.welcomeMessageMode

string

default:automatic

This is the mode of the welcome message. It can be one of the following: 'assistant-speaks-first', 'assistant-waits-for-user', 'automatic'.

Example:

"assistant-speaks-first"

assistant.welcomeMessageInterruptionsEnabled

boolean

default:false

This is a boolean that controls whether the interruptions are enabled during the welcome message. If set to false, the user can not interrupt the welcome message.

Example:

false

assistant.assistantProvider

enum<string>

default:azure

This is the provider of the assistant.

Available options:

openai,

azure,

gemini,

deepseek,

bedrock,

custom-llm

Example:

"openai"

assistant.assistantModel

string

default:gpt-4o-mini

The type of model used for the assistant depends on the provider.

For openai - Available Options: gpt-4, gpt-4o, gpt-4o-mini, gpt-3.5-turbo.

For azure - Available Options: gpt-4, gpt-4o, gpt-4o-mini.

For gemini - Available Options: gemini-1.5-flash-latest,gemini-1.5-pro-latest,gemini-1.5-flash.

For deepseek - Available Options: V3.

For bedrock - Available Options: anthropic.claude-3-5-sonnet, anthropic.claude-3-5-haiku, meta.llama3-1-8b-instruct.

Example:

"gpt-4o-mini"

assistant.assistantLLMUrl

string

Provider your LLM Base URL here when assistantProvider=custom-llm.

Ex: https://your-server.com/custom-llm.

Please note that, we will append /chat/completions to your base URL before calling LLM endpoints. The LLM URL should be accessible from the Interactly server. If you are using a local server, you can use ngrok to expose your local server to the internet.

assistant.assistantSystemPrompt

string

This system prompt guides the assistant's operations.

Example:

"You are AI assistant to help patients with their health care needs."

assistant.assistantTemperature

number

default:0

This is the temperature of the assistant.

Example:

0

assistant.assistantMaxTokens

integer

default:256

This is the maximum number of tokens that the assistant can generate.

Example:

256

assistant.assistantResponseSplitter

string

Use this Delimiter to split the AI responses into separate lines.

Example:

","

assistant.config

object

This is the stt and tts configuration of the assistant. You can add one stt and multiple tts configurations.

Show child attributes

assistant.config.speech

object

Show child attributes

assistant.config.speech.stt

Microsoft STT · object

This section allows you to configure the transcription settings for the assistant.

Microsoft STT
Deepgram STT

Show child attributes

assistant.config.speech.stt.vendor

enum<string>

default:microsoft

This is the vendor of the speech to text.

Available options:

microsoft

Example:

"microsoft"

assistant.config.speech.stt.languages

enum<string>[]

This is the list of languages that the assistant can understand.

Available options:

en-US,

en-IN,

en-GB,

es-US,

es-MX,

fr-FR,

fr-CA,

zh-CN,

pt-BR,

pt-PT,

hi-IN

Example:

"en-US"

assistant.config.speech.ttsData

(Eleven Labs TTS · object | Deepgram TTS · object | Microsoft TTS · object | Cartesia TTS · object)[]

This is the text to speech configuration of the assistant. You can add multiple tts configurations.

Eleven Labs TTS
Deepgram TTS
Microsoft TTS
Cartesia TTS

Show child attributes

assistant.config.speech.ttsData.vendor

enum<string>

Available options:

eleven-labs

Example:

"eleven-labs"

assistant.config.speech.ttsData.language

enum<string>

This is the language of the text to speech.

Available options:

en-US,

es-US,

fr-FR,

zh-CN,

hi-IN

Example:

"en-US"

assistant.config.speech.ttsData.voice

string

Provider voice ID. Ex: Voice ID will be ZeK6O9RfGNGj0cJT2HoJ for Shanaya (female)-Customer Care Agent voice.

Example:

"ZeK6O9RfGNGj0cJT2HoJ"

assistant.hints

string[]

Provide keyword hints to help the assistant better recognize and transcribe important words or phrases.

assistant.backgroundSound

This is the background sound in the call. Default is 'disable'. You can also provide a custom sound by providing a URL to an audio file. URL should be publicly accessible and should starts with https:// only.

Note: Currently custom sound is not supported in twilio phone vendor.

Available options:

enable,

disable

Maximum string length: 1000

Example:

"enable"

assistant.backgroundSoundVolume

number

default:50

This is the volume of the background sound. It is a number between 1 and 100.

Example:

50

assistant.assistantBackchannelingEnabled

boolean

This is the backchanneling enabled of the assistant.

Example:

false

assistant.dtmfInputEnabled

boolean

This is a boolean that controls whether the DTMF input is enabled for the assistant.

Example:

false

assistant.maxCallDuration

integer

This is the max call duration(in minutes) of the assistant.

Required range: 1 <= x <= 120

Example:

900

assistant.idleTimeout

integer

default:30

How long should the assistant wait in silence before confirming the user's presence and playing an idle message?

Required range: 5 <= x <= 600

Example:

20

assistant.maxIdleMessagesInSequence

integer

Maximum number of times to repeat the idle message in sequence

Required range: 1 <= x <= 5

Example:

3

assistant.startSpeakingOptions

object

Configuration for when the assistant should start talking.

Show child attributes

assistant.startSpeakingOptions.waitSeconds

number

default:0

Number of seconds to wait before starting to process speech

assistant.startSpeakingOptions.smartEndpointing

enum<string>

default:Interactly

Controls the endpointing strategy for detecting when a user has finished speaking

Available options:

Interactly,

Off,

LiveKit

assistant.startSpeakingOptions.onPunctuationSeconds

number

default:0

The minimum number of seconds to wait after transcription ending with punctuation before sending a request to the model.

This is only used if smartEndpointing is set to Off.

assistant.startSpeakingOptions.onNoPunctuationSeconds

number

default:0

The minimum number of seconds to wait after transcription ending without punctuation before sending a request to the model.

This is only used if smartEndpointing is set to Off.

assistant.startSpeakingOptions.onNumberSeconds

number

default:0

The minimum number of seconds to wait after transcription ending with a number before sending a request to the model.

This is only used if smartEndpointing is set to Off.

assistant.startSpeakingOptions.LiveKitBaseValue

number

default:100

In the expression where X is the probability that the user is still speaking: LiveKitBaseValue + (LiveKitScaleValue * X) This is the base timeout value in milliseconds.

This is only used if smartEndpointing is set to LiveKit.

assistant.startSpeakingOptions.LiveKitScaleValue

number

default:1000

In the expression where X is the probability that the user is still speaking: LiveKitBaseValue + (LiveKitScaleValue * X) This is the scaling factor for LiveKit endpointing that adjusts based on speech probability.

This is only used if smartEndpointing is set to LiveKit.

assistant.stopSpeakingOptions

object

Configuration for detecting when when assistant should stop talking on customer interruption.

Show child attributes

assistant.stopSpeakingOptions.numberOfWords

number

default:3

This is the number of words that the customer has to say before the assistant will stop talking.

assistant.stopSpeakingOptions.voiceSeconds

number

default:0

This is the seconds customer has to speak before the assistant stops talking. This uses the VAD (Voice Activity Detection) spike to determine if the customer has started speaking.

assistant.assistantToolIds

string[]

This is the list of tool IDs of the assistant.

Example:

[]

assistant.assistantPredefinedTools

object

Enable or disable specific tools that the assistant can use to improve its functionality.

Show child attributes

assistant.assistantPredefinedTools.knowledgeBase

boolean

default:false

This will allow the assistant to end the call from its side.

assistant.assistantPredefinedTools.endCall

boolean

default:false

This will allow the assistant to end the call from its side.

assistant.assistantPredefinedTools.appointment

boolean

default:false

This will allow the assistant to manage appointments, including scheduling, rescheduling, and cancellations.

assistant.assistantPredefinedTools.volumeControl

boolean

default:false

This will allow the assistant to adjust the call volume.

assistant.assistantPredefinedTools.waitList

boolean

default:false

This will allow the assistant to access the wait list.

assistant.assistantPredefinedTools.callForward

boolean

default:false

This will allow the assistant to forward calls to the desired recipient or queue.

assistant.assistantKnowledgeBaseIds

string[]

This is the list of knowledge base IDs of the assistant. Provide only when assistantPredefinedTools.knowledgeBase is enabled

Example:

[]

assistant.endCallMessage

string

This is the message that the assistant will say if it ends the call. Provide only when assistantPredefinedTools.endCall is enabled

Example:

"Goodbye!"

assistant.endCallToolDescription

string

This is the description of the tool that the assistant will use to end the call. Provide only when assistantPredefinedTools.endCall is enabled

Example:

"Trigger the end call only when the user is done with the conversation."

assistant.endCallPhrases

string[]

List of phrases that the assistant will listen to end the call. Provide only when assistantPredefinedTools.endCall is enabled

Example:

["goodbye", "bye"]

assistant.callForwardData

object[]

This is the call-forwarding data of the assistant.

Show child attributes

assistant.callForwardData.phoneNumber

string

Phone number used to forward the call.

Example:

"+1234567890"

assistant.callForwardData.extension

string

This is the extension of the assistant. Leave it empty if there is no extension.

Example:

""

assistant.callForwardData.name

string

This is a friendly name for the call forward.

Example:

"call-forward-name"

Example:

{
  "phoneNumber": "+1234567890",
  "extension": "",
  "name": "call-forward-name"
}

assistant.assistantAnalysis

object

Show child attributes

assistant.assistantAnalysis.summary

object

This is the plan for generating the summary of the call. This outputs to call.analysis.summary.

Show child attributes

assistant.assistantAnalysis.summary.enabled

boolean

This is a boolean that controls whether the summary is generated. If set to false, the model will not generate a summary of the call.

@default false

Example:

false

assistant.assistantAnalysis.summary.prompt

string

This is the prompt that the model will use to generate the summary of the call.

Example:

"Generate a summary of the call."

assistant.assistantAnalysis.summary.timeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.summary will be empty. Usage:

To guarantee the summary is generated, set this value high. Note, this will delay the end of call report in cases where model is slow to respond. @default 5 seconds

Required range: 1 <= x <= 60

Example:

30

assistant.assistantAnalysis.successEvaluation

object

This is the plan for generating the success evaluation of the call. This outputs to call.analysis.successEvaluation.

Show child attributes

assistant.assistantAnalysis.successEvaluation.enabled

boolean

This is a boolean that controls whether the success evaluation is generated. If set to false, the model will not generate a success evaluation of the call.

@default false

Example:

false

assistant.assistantAnalysis.successEvaluation.prompt

string

This is the prompt that the model will use to generate the success evaluation of the call.

Example:

"Evaluate the success of the call."

assistant.assistantAnalysis.successEvaluation.rubric

enum<string>

This enforces the rubric of the evaluation. The output is stored in call.analysis.successEvaluation.

Options include:

'NumericScale': A scale of 1 to 10.
'DescriptiveScale': A scale of Excellent, Good, Fair, Poor.
'Checklist': A checklist of criteria and their status.
'Matrix': A grid that evaluates multiple criteria across different performance levels.
'PercentageScale': A scale of 0% to 100%.
'LikertScale': A scale of Strongly Agree, Agree, Neutral, Disagree, Strongly Disagree.
'AutomaticRubric': Automatically break down evaluation into several criteria, each with its own score.
'PassFail': A simple 'true' if call passed, 'false' if not.

Default is 'PassFail'.

Available options:

NumericScale,

DescriptiveScale,

Checklist,

Matrix,

PercentageScale,

LikertScale,

AutomaticRubric,

PassFail

assistant.assistantAnalysis.successEvaluation.timeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.summary will be empty. Usage:

To guarantee the summary is generated, set this value high. Note, this will delay the end of call report in cases where model is slow to respond. @default 5 seconds

Required range: 1 <= x <= 60

Example:

30

assistant.assistantAnalysis.structuredData

object

This is the plan for generating the structured data from the call. This outputs to call.analysis.structuredData.

Show child attributes

assistant.assistantAnalysis.structuredData.enabled

boolean

default:false

This determines whether structured data is generated and stored in call.analysis.structuredData. Defaults to false.

Usage:

If you want to extract structured data, set this to true and provide a schema.

@default false

assistant.assistantAnalysis.structuredData.prompt

string

This is the prompt that the model will use to generate the structured data of the call.

Example:

"Extract structured data from the call."

assistant.assistantAnalysis.structuredData.timeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.structuredData will be empty.

Usage:

To guarantee the structured data is generated, set this value high. Note, this will delay the end of call report in cases where model is slow to respond.

@default 5 seconds

Required range: 1 <= x <= 60

Example:

30

assistant.assistantAnalysis.structuredData.schema

object

This is the schema of the structured data. The output is stored in call.analysis.structuredData.

Complete guide on JSON Schema can be found here.

Show child attributes

assistant.assistantAnalysis.structuredData.schema.type

enum<string>

required

This is the type of output you'd like.

string, number, integer, boolean are the primitive types and should be obvious.

array and object are more interesting and quite powerful. They allow you to define nested structures.

For array, you can define the schema of the items in the array using the items property.

For object, you can define the properties of the object using the properties property.

Available options:

string,

number,

integer,

boolean,

array,

object

assistant.assistantAnalysis.structuredData.schema.items

object

This is required if the type is "array". This is the schema of the items in the array.

This is of type JsonSchema. However, Swagger doesn't support circular references.

assistant.assistantAnalysis.structuredData.schema.properties

object

This is required if the type is "object". This specifies the properties of the object.

This is a map of string to JsonSchema. However, Swagger doesn't support circular references.

assistant.assistantAnalysis.structuredData.schema.description

string

This is the description to help the model understand what it needs to output.

assistant.assistantAnalysis.structuredData.schema.required

string[]

This is a list of properties that are required.

This only makes sense if the type is "object".

Example:

{
  "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"
    }
  }
}

assistant.assistantOverrides

object

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

Show child attributes

assistant.assistantOverrides.welcomeMessage

string

This is the message that the assistant will say when the call starts.

Example:

"Hello, how can I help you today?"

assistant.assistantOverrides.welcomeMessageMode

string

default:automatic

This is the mode of the welcome message. It can be one of the following: 'assistant-speaks-first', 'assistant-waits-for-user', 'automatic'.

Example:

"assistant-speaks-first"

assistant.assistantOverrides.welcomeMessageInterruptionsEnabled

boolean

default:false

This is a boolean that controls whether the interruptions are enabled during the welcome message. If set to false, the user can not interrupt the welcome message.

Example:

false

assistant.assistantOverrides.recordingEnabled

boolean

default:true

This is a boolean that controls whether the recording is enabled. If set to false, the model will not record the call.

@default true

Example:

true

assistant.assistantOverrides.recordingPath

string

This is the path where the recording will be stored. If not provided, the recording will be stored in the default path.

Example:

"/recordings"

assistant.assistantOverrides.dynamicVariables

object

This is the dynamic variables of the conversation. Values in this object will be replaced in the assistant system prompt, welcome message, end call message. If your dynamic variable is user_name, you can use it in the system prompt message as Hello, {{user_name}}.

Example:

{ "user_name": "John Doe" }

assistant.assistantServer

object

This is where Interactly will send webhooks. You can find all webhooks available along with their shape in ServerMessage schema.

Show child attributes

assistant.assistantServer.url

string

required

API endpoint to send requests to.

Example:

"https://api.example.com/v1/getUserDetails"

assistant.assistantServer.timeoutSeconds

number

This is the timeout in seconds for the request to your server. Defaults to 20 seconds.

@default 20

Required range: 1 <= x <= 120

Example:

20

assistant.assistantServer.secret

string

This is the secret you can set that Interactly will send with every request to your server. Will be sent as a header called x-interactly-secret.

Example:

"my-secret"

assistant.assistantServer.headers

object

These are the custom headers to include in the request sent to your server.

Each key-value pair represents a header name and its value.

Example:

{}

assistant.assistantServer.enabled

boolean

This is a boolean that controls whether the server is enabled. If set to false, the model will not send webhooks to the server.

@default false

Example:

false

assistant.assistantServer.messages

enum<string>[]

These are the messages that will be sent to your Server URL.

Available options:

status-update,

conversation-update,

hang,

end-of-call-report

Example:

[
  "status-update",
  "conversation-update",
  "hang",
  "end-of-call-report"
]

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.

Show child attributes

assistantOverrides.welcomeMessage

string

This is the message that the assistant will say when the call starts.

Example:

"Hello, how can I help you today?"

assistantOverrides.welcomeMessageMode

string

default:automatic

This is the mode of the welcome message. It can be one of the following: 'assistant-speaks-first', 'assistant-waits-for-user', 'automatic'.

Example:

"assistant-speaks-first"

assistantOverrides.welcomeMessageInterruptionsEnabled

boolean

default:false

This is a boolean that controls whether the interruptions are enabled during the welcome message. If set to false, the user can not interrupt the welcome message.

Example:

false

assistantOverrides.recordingEnabled

boolean

default:true

This is a boolean that controls whether the recording is enabled. If set to false, the model will not record the call.

@default true

Example:

true

assistantOverrides.recordingPath

string

This is the path where the recording will be stored. If not provided, the recording will be stored in the default path.

Example:

"/recordings"

assistantOverrides.dynamicVariables

object

Example:

{ "user_name": "John Doe" }

Response

200 - application/json

Successful response

string

This is the unique identifier of the call.

Example:

"CC-897ee2d4-ea2f-4958-889f-df381bdfc939"

teamId

string

This is the unique identifier of the team that the call belongs to.

Example:

"1f7b1b1b1b1b1b1b1b1b1b1b"

assistantId

string

ID of the assistant that will be used for the call.

Example:

"678a253ca6d866573043502e"

phoneNumberId

string

Unique phone number ID. This is the phone number that will be used to make the call.

Example:

"5f7b1b1b1b1b1b1b1b1b1b1b"

direction

enum<string>

default:outbound

This is the direction of the conversation.

Inbound - The conversation is initiated by the user. Outbound - The conversation is initiated by the assistant.

Available options:

inbound,

outbound

Example:

"outbound"

createdAt

string<date-time>

This is the ISO 8601 date-time string of when the record was created.

Example:

"2020-10-05T00:00:00.000Z"

updatedAt

string<date-time>

This is the ISO 8601 date-time string of when the record was last updated.

Example:

"2020-10-05T00:00:00.000Z"

customer

object

Show child attributes

customer.number

string

This is the number of the customer.

customer.name

string

This is the name of the customer. This is just for your own reference.

status

enum<string>

default:queued

This is the status of the call.

Available options:

queued,

ongoing,

completed,

forwarded

Example:

"queued"

metadata

object

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

Example:

{ "key": "value" }

phoneVendor

enum<string>

default:twilio

This is the vendor of the phone number.

Available options:

twilio,

bandwidth

Example:

"twilio"

phoneVendorDetails

object

This is the vendor details of the phone number.

Show child attributes

phoneVendorDetails.from

string

This is the phone number of the sender.

Example:

"+1234567890"

phoneVendorDetails.to

string

This is the phone number of the receiver.

Example:

"+1234567890"

phoneVendorDetails.twiml

string

This is the twiml response to be given to twilio.

Example:

"twiml-response-tobe-given-to-twilio"

phoneVendorDetails.responseType

enum<string>

This is the response type of the phone number.

Available options:

text/xml,

application/json

Example:

"text/xml"

phoneVendorDetails.statusCallback

string

This is status callback websocket URL. Using this URL you can get the status of the call.

Example:

"https://<domain>.interactly.ai/voice/twilio/call-status/<call-id>"

phoneVendorDetails.statusCallbackEvent

enum<string>[]

This is the status callback event of the phone number.

Available options:

initiated,

ringing,

answered,

completed

monitor

object

To monitor and control the conversation

Show child attributes

monitor.controlUrl

string

The URL to control the conversation

Example:

"https://<domain>.interactly.ai/calls/v1/conversations/<random-id>/control"

Getting Started

APIs

Campaigns

Authorizations

Body

Response