--- title: "Connect Call" method: POST path: "/calls/v1/conversations/connect" tags: ["Calls"] --- # Connect Call `POST /calls/v1/conversations/connect` Connect your call with Interactly. ## Request body - ConnectConversationDTO - `direction` 'inbound' | '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. - `phoneNumberId` string, required — Unique phone number ID. This is the phone number that will be used to make the call. - `customer` Customer, required - `number` string — This is the number of the 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. - `assistant` AssistantCommon - `name` string — This is the name of the assistant. - `welcomeMessage` string — This is the welcome message of the assistant. - `welcomeMessageMode` string — This is the mode of the welcome message. It can be one of the following: 'assistant-speaks-first', 'assistant-waits-for-user', 'automatic'. - `welcomeMessageInterruptionsEnabled` boolean — 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. - `assistantProvider` 'openai' | 'azure' | 'gemini' | 'deepseek' | 'bedrock' | 'custom-llm' — This is the provider of the assistant. - `assistantModel` string — 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`. - `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. - `assistantSystemPrompt` string — This system prompt guides the assistant's operations. - `assistantTemperature` number — This is the temperature of the assistant. - `assistantMaxTokens` integer — This is the maximum number of tokens that the assistant can generate. - `assistantResponseSplitter` string — Use this Delimiter to split the AI responses into separate lines. - `config` AssistantConfig — This is the stt and tts configuration of the assistant. You can add one stt and multiple tts configurations. check [here](/vendors) for the list of supported vendors and models. - `speech` object - `stt` union — This section allows you to configure the transcription settings for the assistant. - MicrosoftSTT - `vendor` 'microsoft' — This is the vendor of the speech to text. - `languages` string[] — This is the list of languages that the assistant can understand. - DeepgramSTT - `vendor` 'deepgram' — This is the vendor of the speech to text. - `languages` string[] — This is the list of languages that the assistant can understand. - `deepgramOptions` object — This is the configuration of the deepgram text to speech. - … - `sttFallback` union - object — This flag can enable or disable the fallback stt configuration. - `enabled` boolean - `vendor` 'microsoft' — This is the vendor of the speech to text. - `languages` string[] — This is the list of languages that the assistant can understand. - object — This flag can enable or disable the fallback stt configuration. - `enabled` boolean - `vendor` 'deepgram' — This is the vendor of the speech to text. - `languages` string[] — This is the list of languages that the assistant can understand. - `deepgramOptions` object — This is the configuration of the deepgram text to speech. - … - `ttsData` union[] — This is the text to speech configuration of the assistant. You can add multiple tts configurations. - union - object - … - object - … - object - … - object - … - `hints` string[] — Provide keyword hints to help the assistant better recognize and transcribe important words or phrases. - `backgroundSound` union — 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. - 'enable' | 'disable' - string, uri - `backgroundSoundVolume` number — This is the volume of the background sound. It is a number between 1 and 100. - `ttsCacheEnabled` boolean — This is the enabled flag of the tts cache. - `ttsAudioCacheScope` 'assistant' | 'team' | 'global' — This is the storage scope of the tts audio cache. It can be one of the following: 'assistant', 'team', 'global'. 'global' is deprecated and will be removed in future. - `maxConsecutiveTtsFailures` integer — Maximum number of consecutive TTS turn failures before the call is ended automatically. - `recordingEnabled` boolean — Controls whether call recording is enabled for this assistant. - `recordAfterTransfer` boolean — When enabled, call recording continues after the call is forwarded or warm-transferred to another party. - `postCallTranscriptsEnabled` boolean — When enabled, a post-call transcript file is generated and stored alongside the call recording after the call ends. - `assistantBackchannelingEnabled` boolean — This is the backchanneling enabled of the assistant. - `dtmfInputEnabled` boolean — This is a boolean that controls whether the DTMF input is enabled for the assistant. - `maxCallDuration` integer — This is the max call duration(in minutes) of the assistant. - `idleTimeout` integer — How long should the assistant wait in silence before confirming the user's presence and playing an idle message? - `maxIdleMessagesInSequence` integer — Maximum number of times to repeat the idle message in sequence - `startSpeakingOptions` object — Configuration for when the assistant should start talking. - `waitSeconds` number — Number of seconds to wait before starting to process speech - `smartEndpointing` 'Interactly' | 'Off' | 'LiveKit' — Controls the endpointing strategy for detecting when a user has finished speaking - `onPunctuationSeconds` number — 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`. - `onNoPunctuationSeconds` number — 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`. - `onNumberSeconds` number — 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`. - `LiveKitBaseValue` number — 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`. - `LiveKitScaleValue` number — 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`. - `stopSpeakingOptions` object — Configuration for detecting when when assistant should stop talking on customer interruption. - `numberOfWords` number — This is the number of words that the customer has to say before the assistant will stop talking. - `voiceSeconds` number — 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. - `userInterruptionAckPlan` object — This is the plan to respond to early interruptions by user with polite filler phrases. - `enabled` boolean — This is the enabled flag of the user interruption ack plan. - `count` number — This is the number of times the user will interrupt the assistant before responding with a polite filler phrase. - `words` number — This is the number of words that the user will interrupt the assistant - `phrases` string[] — This is the list of phrases that the assistant will use to respond to the user's early interruptions. - `assistantToolIds` string[] — This is the list of tool IDs of the assistant. - `assistantPredefinedTools` object — Enable or disable specific tools that the assistant can use to improve its functionality. - `knowledgeBase` boolean — This will allow the assistant to end the call from its side. - `endCall` boolean — This will allow the assistant to end the call from its side. - `appointment` boolean — This will allow the assistant to manage appointments, including scheduling, rescheduling, and cancellations. - `volumeControl` boolean — This will allow the assistant to adjust the call volume. - `waitList` boolean — This will allow the assistant to access the wait list. - `callForward` boolean — This will allow the assistant to forward calls to the desired recipient or queue. - `sendSms` boolean — This will allow the assistant to send SMS messages during the call. - `interactionLookup` boolean — Enables interaction lookup (Dynamic Assistant). When enabled, callhook hits `interactionLookupData` to resolve an assistant or list of interactions. - `assistantType` 'single_prompt' | 'workflow_based' — This is the type of the assistant. It can be one of the following: 'single_prompt', 'workflow_based'. - `assistantKnowledgeBaseIds` string[] — This is the list of knowledge base IDs of the assistant. Provide only when `assistantPredefinedTools.knowledgeBase` is enabled - `endCallMessage` string — This is the message that the assistant will say if it ends the call. Provide only when `assistantPredefinedTools.endCall` is enabled - `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 - `endCallPhrases` string[] — List of phrases that the assistant will listen to end the call. Provide only when `assistantPredefinedTools.endCall` is enabled - `callForwardData` object[] — This is the call-forwarding data of the assistant. - `phoneNumber` string — Phone number used to forward the call. - `extension` string — This is the extension of the assistant. Leave it empty if there is no extension. - `name` string — This is a friendly name for the call forward. - `onFailedMessage` string — This is the message that the assistant will say if the call forward fails. - `interactionLookupData` object — API details for interaction lookup (Dynamic Assistant), used when `assistantPredefinedTools.interactionLookup` is enabled. Callhook POSTs `assistantNumber`, `userNumber`, and `assistantId` (plus optional user text / callSid). Expected response: `{ assistant: , interactions: }`. If `assistant` is set it is used; if null, the caller is asked to pick from `interactions`. - `url` string — Customer endpoint URL for interaction lookup. - `timeoutSeconds` number — HTTP timeout in seconds for the lookup request. - `secret` string — Optional shared secret sent with the lookup request. - `headers` object — Optional HTTP headers for the lookup request. - `method` string — HTTP method for the lookup request. - `warmTransferEnabled` boolean — Enables warm transfer when forwarding calls. The receiving agent is connected before the caller is transferred, allowing a briefing before handoff. Requires `assistantPredefinedTools.callForward` to be enabled. - `warmTransferConversational` boolean — When enabled with `warmTransferEnabled`, the assistant converses with the receiving agent before completing the transfer. When disabled, a pre-generated briefing message is played to the agent instead. - `holdMusicUrl` string — URL of the hold music played to the caller while a conversational warm transfer is in progress. Must be a publicly accessible HTTPS URL. - `warmTransferTimeout` integer — Maximum time in seconds to wait for the receiving agent to answer during a warm transfer before the transfer is considered failed. - `assistantAnalysis` AssistantAnalysis - `summary` AssistantAnalysisSummary - `temperature` number — This is the temperature for the analysis LLM request. - `maxTokens` integer — This is the maximum number of tokens that the analysis LLM can generate. - `thinkingBudget` integer — This is the thinking budget for models that support extended reasoning. - `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 - `prompt` string — This is the prompt that the model will use to generate the summary of the call. - `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 - `successEvaluation` AssistantAnalysisSuccessEvaluation - `temperature` number — This is the temperature for the analysis LLM request. - `maxTokens` integer — This is the maximum number of tokens that the analysis LLM can generate. - `thinkingBudget` integer — This is the thinking budget for models that support extended reasoning. - `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 - `prompt` string — This is the prompt that the model will use to generate the success evaluation of the call. - `rubric` 'NumericScale' | 'DescriptiveScale' | 'Checklist' | 'Matrix' | 'PercentageScale' | 'LikertScale' | 'AutomaticRubric' | 'PassFail' — 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'. - `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 - `structuredData` AssistantAnalysisStructuredData - `temperature` number — This is the temperature for the analysis LLM request. - `maxTokens` integer — This is the maximum number of tokens that the analysis LLM can generate. - `thinkingBudget` integer — This is the thinking budget for models that support extended reasoning. - `enabled` boolean — 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 - `prompt` string — This is the prompt that the model will use to generate the structured data of the call. - `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 - `schema` JsonSchema - `type` 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object', 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. - `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. - `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. - `description` string — This is the description to help the model understand what it needs to output. - `required` string[] — This is a list of properties that are required. This only makes sense if the type is "object". - `assistantOverrides` AssistantOverrides — This is where you can override the default behavior of the assistant. - `welcomeMessage` string — This is the message that the assistant will say when the call starts. - `welcomeMessageMode` string — This is the mode of the welcome message. It can be one of the following: 'assistant-speaks-first', 'assistant-waits-for-user', 'automatic'. - `welcomeMessageInterruptionsEnabled` boolean — 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. - `recordingEnabled` boolean — This is a boolean that controls whether the recording is enabled. If set to false, the model will not record the call. @default true - `recordAfterTransfer` boolean — When enabled, call recording continues after the call is forwarded or warm-transferred to another party. - `postCallTranscriptsEnabled` boolean — When enabled, a post-call transcript file is generated and stored alongside the call recording after the call ends. - `maxConsecutiveTtsFailures` integer — Maximum number of consecutive TTS turn failures before the call is ended automatically. - `warmTransferEnabled` boolean — Enables warm transfer when forwarding calls. The receiving agent is connected before the caller is transferred. - `warmTransferConversational` boolean — When enabled with `warmTransferEnabled`, the assistant converses with the receiving agent via WebSocket before completing the transfer. - `holdMusicUrl` string — URL of the hold music played to the caller while a conversational warm transfer is in progress. - `warmTransferTimeout` integer — Maximum time in seconds to wait for the receiving agent to answer during a warm transfer. - `recordingPath` string — This is the path where the recording will be stored. If not provided, the recording will be stored in the default path. - `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}}`. - `assistantServer` AssistantServer - `timeoutSeconds` number — This is the timeout in seconds for the request to your server. Defaults to 20 seconds. @default 20 - `url` string, required — API endpoint to send requests to. - `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. - `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. - `assistantOutcome` object[] - `type` string — This is the type of the outcome. - `field` string — This is the field of the outcome. - `smsConfiguration` object — Control how the assistant composes outbound SMS. - `enabled` boolean — This is the enabled flag of the sms configuration. - `sameAsAssistant` boolean — Use the same prompt as the assistant, or provide a custom SMS prompt. - `smsPrompt` string — This is the sms prompt for handling sms responses. - `persistHistory` object — Remember users and keep conversation history for follow-ups. - `enabled` boolean — This is the enabled flag of the persist history. - `call` boolean — Store metadata and transcripts of calls in persisted data for future personalization and context. - `sms` boolean — Keep outbound and inbound SMS content so follow-ups can reference earlier messages. - `retentionPeriod` number — This is, how long(in number of days) to retain persisted data. Set to 0 to keep nothing. - `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. - `assistantOverrides` AssistantOverrides — This is where you can override the default behavior of the assistant. - `welcomeMessage` string — This is the message that the assistant will say when the call starts. - `welcomeMessageMode` string — This is the mode of the welcome message. It can be one of the following: 'assistant-speaks-first', 'assistant-waits-for-user', 'automatic'. - `welcomeMessageInterruptionsEnabled` boolean — 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. - `recordingEnabled` boolean — This is a boolean that controls whether the recording is enabled. If set to false, the model will not record the call. @default true - `recordAfterTransfer` boolean — When enabled, call recording continues after the call is forwarded or warm-transferred to another party. - `postCallTranscriptsEnabled` boolean — When enabled, a post-call transcript file is generated and stored alongside the call recording after the call ends. - `maxConsecutiveTtsFailures` integer — Maximum number of consecutive TTS turn failures before the call is ended automatically. - `warmTransferEnabled` boolean — Enables warm transfer when forwarding calls. The receiving agent is connected before the caller is transferred. - `warmTransferConversational` boolean — When enabled with `warmTransferEnabled`, the assistant converses with the receiving agent via WebSocket before completing the transfer. - `holdMusicUrl` string — URL of the hold music played to the caller while a conversational warm transfer is in progress. - `warmTransferTimeout` integer — Maximum time in seconds to wait for the receiving agent to answer during a warm transfer. - `recordingPath` string — This is the path where the recording will be stored. If not provided, the recording will be stored in the default path. - `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}}`. ## Response `200` Successful response - ConnectConversationResponseDTO - `id` string — This is the unique identifier of the call. - `teamId` string — This is the unique identifier of the team that the call belongs to. - `assistantId` string — ID of the assistant that will be used for the call. - `phoneNumberId` string — Unique phone number ID. This is the phone number that will be used to make the call. - `direction` 'inbound' | 'outbound' — This is the direction of the conversation. Inbound - The conversation is initiated by the user. Outbound - The conversation is initiated by the assistant. - `createdAt` string, date-time — This is the ISO 8601 date-time string of when the record was created. - `updatedAt` string, date-time — This is the ISO 8601 date-time string of when the record was last updated. - `customer` Customer - `number` string — This is the number of the customer. - `name` string — This is the name of the customer. This is just for your own reference. - `status` 'queued' | 'ongoing' | 'completed' | 'forwarded' — This is the status of the call. - `metadata` object — This is the metadata of the conversation. You can add any additional information here. - `phoneVendor` 'twilio' | 'bandwidth' — This is the vendor of the phone number. - `phoneVendorDetails` object — This is the vendor details of the phone number. - `from` string — This is the phone number of the sender. - `to` string — This is the phone number of the receiver. - `twiml` string — This is the twiml response to be given to twilio. - `responseType` 'text/xml' | 'application/json' — This is the response type of the phone number. - `statusCallback` string — This is status callback websocket URL. Using this URL you can get the status of the call. - `statusCallbackEvent` string[] — This is the status callback event of the phone number. - `monitor` ConversationMonitor — To monitor and control the conversation - `controlUrl` string — The URL to control the conversation --- [API](https://skmtc.net/interactly/apis/interactly-api.md) · [All operations](https://skmtc.net/interactly/apis/interactly-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/interactly/interactly-api/versions/f39cdcb1f4e4/schema)