Sign in

v1

latestOpenAPI 3.0.12026-07-226992320.0 KB
Calls

Create Phone Call

Initiates an outbound call with the specified agent, caller, and destination numbers. Supports dynamic variables for personalization. Returns the created call record, including the callId for future retrieval or cancellation.

post/v1/calls

Request body

fromPhoneNumberstring required

Caller's phone number in +E.164 format (e.g., +14155552671). Must be a number provisioned in SigmaMind or configured via SIP trunking that is enabled for outbound calls. This number appears as the caller ID on the recipient's device.

toPhoneNumberstring required

Destination phone number to dial, in +E.164 format (e.g., +14155552671). Must be a valid number capable of receiving calls. Include the country code — local-format numbers without a leading '+' are rejected.

agentIdstring

Unique identifier of the agent that will handle this call. The agent controls the conversation flow, prompts, and any tools invoked during the call. If omitted, the default agent configured for the caller's phone number is used.

dynamicVariablesobject

Key-value pairs used to personalise the agent's behaviour for this specific call. Keys must match the variable names defined in the agent's configuration (e.g., 'customer_name', 'account_id'). These values are injected into the agent's prompts and tools at call start. Leave empty if the agent requires no personalisation.

Example request

{
  "fromPhoneNumber": "+14155552671",
  "toPhoneNumber": "+14155552671",
  "agentId": "D5D0p7TUs66TTAEAx",
  "dynamicVariables": {
    "customer_name": "Michael",
    "account_id": "ACC-001"
  }
}

Response

Created

callIdstring

Unique identifier for this call. Use this value as callId when retrieving, updating, or referencing this call in subsequent API calls.

callType'inbound' | 'outbound' | 'web' | 'chat'

Direction and channel of the call. 'inbound' means the call was received by SigmaMind from an external caller. 'outbound' means SigmaMind dialled the destination number. 'web' means the call originated from a browser-based session.

status'scheduled' | 'in_progress' | 'ended' | 'not_connected' | 'error'

Current lifecycle state of the call. 'scheduled' means the call is queued but dialling has not started. 'in_progress' means the call is currently active. 'ended' means the call completed normally. 'not_connected' means the call was attempted but the recipient did not answer or connect. 'error' means the system encountered a failure while trying to place or manage the call.

transcriptstring

transcript of the conversation in chat

startTimestring date-time

UTC timestamp when the call was connected and the active session began, in ISO 8601 format. Null if the call never reached in_progress state.

endTimestring date-time

UTC timestamp when the call session ended, in ISO 8601 format. Null if the call is still in progress or was never connected.

durationinteger

Total duration of the connected call session in seconds. Measured from startTime to endTime. Null if the call was never connected.

terminationReason'silence_timed_out' | 'agent_ended_call' | 'user_ended_call' | 'voicemail_detected' | 'ivr_detected' | 'agent_transferred_call' | 'max_call_duration_exceeded' | 'dial_telephony_permission_denied' | 'dial_invalid_destination' | 'dial_no_answer' | 'dial_user_declined' | 'dial_busy' | 'dial_failed' | 'error_credit_limit_reached' | 'error_llm' | 'error_tts' | 'error_asr' | 'error_sigmamind' | 'error_telephony' | 'error_unknown'

Reason the call session ended. 'silence_timed_out' — call ended due to configured silence timeout. 'agent_ended_call' — the AI agent closed the session. 'user_ended_call' — the recipient hung up the call. 'voicemail_detected' — voicemail was detected during the call. 'ivr_detected' — IVR system was detected during the call. 'agent_transferred_call' — the AI agent transferred the call. 'max_call_duration_exceeded' — maximum call duration limit was exceeded. 'dial_telephony_permission_denied' — outbound dialing permission was denied by telephony provider. 'dial_invalid_destination' — destination number was invalid. 'dial_no_answer' — the call rang but was not answered. 'dial_user_declined' — recipient declined the incoming call. 'dial_busy' — the destination number was busy. 'dial_failed' — outbound dialing failed due to SIP or telephony error. 'error_credit_limit_reached' — insufficient credit balance. 'error_llm' — language model failed to generate a response. 'error_tts' — text-to-speech service error occurred. 'error_asr' — speech recognition service error occurred. 'error_sigmamind' — internal SigmaMind processing error occurred. 'error_telephony' — telephony provider or connection error occurred. 'error_unknown' — unknown internal error occurred. Null if the call has not yet ended.

createdAtstring date-time

UTC timestamp when this call record was created in the system, in ISO 8601 format. For outbound calls this is typically when the call was scheduled or triggered.

updatedAtstring date-time

UTC timestamp when this call record was last updated, in ISO 8601 format. Updates occur when the call status changes, the session ends, or metadata is modified.

dynamicVariablesJsonNode

Dynamic key-value pairs that were passed to the agent at call start for personalisation. Keys correspond to variable names defined in the agent's configuration (e.g., 'customer_name', 'account_id'). Null or empty if no dynamic variables were provided when the call was created.

recordingUrlstring

URL of the call recording audio file. Available after the call ends and recording processing is complete. Null if recording is not enabled for this call or if the call did not connect.

Example response

{
  "callId": "call_AuUKK371Spr5nHJS",
  "callType": "outbound",
  "phoneNumber": {
    "sipPhoneNumber": "+14155552671",
    "provider": "twilio",
    "inboundAgentId": "agent_D5D0p7TUs66TTAEAx",
    "outboundAgentId": "agent_D5D0p7TUs66TTAEAx",
    "outboundPhoneNumber": "+14155552671",
    "active": true,
    "terminationSipURI": "sip.telnyx.com",
    "friendlyName": "Support Line - US"
  },
  "campaign": {
    "campaignId": "camp_XiQEBcj9cc5TFRB4",
    "campaignName": "Q4 Outreach Campaign",
    "campaignStatus": "live",
    "scheduledDate": "2025-09-25T19:00:00.000Z",
    "concurrentCalls": 5,
    "agent": {
      "name": "New AI Agent",
      "agentId": "agent_D5D0p7TUs66TTAEAx",
      "status": "Live"
    },
    "phoneNumber": {
      "sipPhoneNumber": "+14155552671",
      "provider": "twilio",
      "inboundAgentId": "agent_D5D0p7TUs66TTAEAx",
      "outboundAgentId": "agent_D5D0p7TUs66TTAEAx",
      "outboundPhoneNumber": "+14155552671",
      "active": true,
      "terminationSipURI": "sip.telnyx.com",
      "friendlyName": "Support Line - US"
    },
    "errors": [
      "Row 3: missing required variable 'customer_name'",
      "Row 7: invalid phone number '+1234'"
    ]
  },
  "status": "ended",
  "startTime": "2024-04-20T10:00:00.000Z",
  "endTime": "2024-04-20T10:02:00.000Z",
  "duration": 120,
  "terminationReason": "user_ended_call",
  "createdAt": "2024-04-20T09:59:50.000Z",
  "updatedAt": "2024-04-20T10:02:05.000Z",
  "dynamicVariables": {
    "customer_name": "Michael",
    "account_id": "ACC-001"
  },
  "recordingUrl": "https://livekitmedia.blob.core.windows.net/recording-container-prod/room-ST_abc123/recording.mp3",
  "agent": {
    "name": "New AI Agent",
    "agentId": "agent_D5D0p7TUs66TTAEAx",
    "status": "Live"
  }
}