Sign in

v2

latestOpenAPI 3.1.02026-07-313981108.2 KB
Calls

Connect Call

Connect your call with Interactly.

post/calls/v1/conversations/connect

Request body

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.

phoneNumberIdstring required

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

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

{
  "direction": "outbound",
  "phoneNumberId": "5f7b1b1b1b1b1b1b1b1b1b1b",
  "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

idstring

This is the unique identifier of the call.

teamIdstring

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

assistantIdstring

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

phoneNumberIdstring

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.

createdAtstring date-time

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

updatedAtstring date-time

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

status'queued' | 'ongoing' | 'completed' | 'forwarded'

This is the status of the call.

metadataobject

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.

Example response

{
  "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",
  "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>"
  },
  "monitor": {
    "controlUrl": "https://<domain>.interactly.ai/calls/v1/conversations/<random-id>/control"
  }
}