Skip to main content
POST
/
calls
/
v1
/
conversations
/
connect
Connect Call
curl --request POST \
  --url https://api-qa.interactly.ai/calls/v1/conversations/connect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "direction": "outbound",
  "phoneNumberId": "5f7b1b1b1b1b1b1b1b1b1b1b",
  "customer": {
    "number": "<string>",
    "name": "<string>"
  },
  "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"
        },
        "ttsData": [
          {
            "vendor": "eleven-labs",
            "language": "en-US",
            "voice": "ZeK6O9RfGNGj0cJT2HoJ"
          }
        ]
      }
    },
    "hints": [
      "<string>"
    ],
    "backgroundSound": "enable",
    "backgroundSoundVolume": 50,
    "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
    },
    "assistantToolIds": [],
    "assistantPredefinedTools": {
      "knowledgeBase": false,
      "endCall": false,
      "appointment": false,
      "volumeControl": false,
      "waitList": false,
      "callForward": false
    },
    "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"
      ]
    }
  },
  "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"
    }
  }
}
'
{
  "id": "CC-897ee2d4-ea2f-4958-889f-df381bdfc939",
  "teamId": "1f7b1b1b1b1b1b1b1b1b1b1b",
  "assistantId": "678a253ca6d866573043502e",
  "phoneNumberId": "5f7b1b1b1b1b1b1b1b1b1b1b",
  "direction": "outbound",
  "createdAt": "2020-10-05T00:00:00.000Z",
  "updatedAt": "2020-10-05T00:00:00.000Z",
  "customer": {
    "number": "<string>",
    "name": "<string>"
  },
  "status": "queued",
  "metadata": {
    "key": "value"
  },
  "phoneVendor": "twilio",
  "phoneVendorDetails": {
    "from": "+1234567890",
    "to": "+1234567890",
    "twiml": "twiml-response-tobe-given-to-twilio",
    "responseType": "text/xml",
    "statusCallback": "https://<domain>.interactly.ai/voice/twilio/call-status/<call-id>",
    "statusCallbackEvent": [
      "initiated"
    ]
  },
  "monitor": {
    "controlUrl": "https://<domain>.interactly.ai/calls/v1/conversations/<random-id>/control"
  }
}

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.

​
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

​
id
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
​
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.

​
monitor
object

To monitor and control the conversation