Trigger Calls

Programmatically trigger outbound voice calls

Base Path

bash

/public/agent/

Route Selection

There are two ways to identify which agent to call:

Parameter	Type	Required	Description
`Trigger UUID`	/public/agent/{uuid}	Optional	From the API Trigger node on the agent's canvas
`Workflow UUID`	/public/agent/workflow/{workflow_uuid}	Optional	From the workflow_uuid field in GET /workflow/fetch

These identifiers are not interchangeable. Do not pass a workflow UUID to the trigger path, and do not pass a trigger UUID to the workflow path.

Endpoints

Method	Path	Description
POST	`/public/agent/{uuid}`	Trigger call — published agent, via trigger UUID
POST	`/public/agent/test/{uuid}`	Trigger call — latest draft, via trigger UUID
POST	`/public/agent/workflow/{workflow_uuid}`	Trigger call — published agent, via workflow UUID
POST	`/public/agent/test/workflow/{workflow_uuid}`	Trigger call — latest draft, via workflow UUID

/test/ variants use the latest draft definition. If no draft exists they fall back to the published version. Use for QA before publishing changes.

Request Body

json

{
  "phone_number": "+14155552671",
  "initial_context": {
    "customer_name": "Jane Smith",
    "account_id": "ACC-1234"
  },
  "telephony_configuration_id": null
}

Parameter	Type	Required	Description
`phone_number`	string	Required	E.164 format — e.g. +14155552671
`initial_context`	object	Optional	Arbitrary key-value pairs. Values become {{template_variables}} accessible in agent prompts.
`telephony_configuration_id`	integer \| null	Optional	Override the telephony config. Defaults to the organisation's default outbound config.

initial_context — how template variables work

Context values are injected into the call runtime. Any key in initial_context becomes a {{variable_name}} accessible in the agent's prompts:

json

{
  "initial_context": {
    "customer_name": "Jane",
    "appointment_date": "March 15",
    "reason_for_call": "renewal reminder"
  }
}

In the agent prompt: "Hi {{customer_name}}, I'm calling about your {{reason_for_call}} scheduled for {{appointment_date}}."

Response

json

{
  "status": "initiated",
  "workflow_run_id": 8421,
  "workflow_run_name": "WR-API-3847"
}

Parameter	Type	Required	Description
`status`	string	Optional	Always "initiated" on success
`workflow_run_id`	number	Optional	Numeric ID of the call session — use to fetch transcript and outcome
`workflow_run_name`	string	Optional	Auto-generated human-readable name

The response is returned immediately. The actual phone call proceeds asynchronously.

Error Reference

Parameter	Type	Required	Description
`400`	HTTP Status	Optional	Telephony provider not configured, or call initiation failed at provider
`401`	HTTP Status	Optional	Invalid or missing X-API-Key
`402`	HTTP Status	Optional	Quota exhausted — minute balance empty or PAYG wallet at zero
`403`	HTTP Status	Optional	Trigger UUID or workflow UUID belongs to a different organisation
`404`	HTTP Status	Optional	Agent not found, not active, trigger not registered in this agent's definition
`409`	HTTP Status	Optional	Agent has no execution owner configured (assign in agent settings)
`422`	HTTP Status	Optional	Invalid phone number format or missing phone_number

Code Examples

curl

bash

curl -X POST https://api.sysevo.io/api/v1/public/agent/3f2a1c4d-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "phone_number": "+14155552671",
    "initial_context": {
      "customer_name": "Jane Smith",
      "account_id": "ACC-1234"
    }
  }'

JavaScript / TypeScript

typescript

async function triggerCall(agentUUID: string, phoneNumber: string, context: Record<string, string>) {
  const res = await fetch(
    `https://api.sysevo.io/api/v1/public/agent/${agentUUID}`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.SYSEVO_API_KEY!,
      },
      body: JSON.stringify({
        phone_number: phoneNumber,
        initial_context: context,
      }),
    }
  );

  if (!res.ok) {
    const err = await res.json();
    throw new Error(`${res.status}: ${err.detail}`);
  }

  return await res.json() as {
    status: string;
    workflow_run_id: number;
    workflow_run_name: string;
  };
}

Python

python

import httpx
from typing import Optional

async def trigger_call(
    agent_uuid: str,
    phone_number: str,
    api_key: str,
    initial_context: Optional[dict] = None,
    telephony_configuration_id: Optional[int] = None,
) -> dict:
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            f"https://api.sysevo.io/api/v1/public/agent/{agent_uuid}",
            headers={"X-API-Key": api_key},
            json={
                "phone_number": phone_number,
                "initial_context": initial_context or {},
                "telephony_configuration_id": telephony_configuration_id,
            },
        )
        resp.raise_for_status()
        return resp.json()

PHP

php

function triggerSysevoCall(string $agentUuid, string $phone, array $context, string $apiKey): array {
    $ch = curl_init("https://api.sysevo.io/api/v1/public/agent/{$agentUuid}");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ["Content-Type: application/json", "X-API-Key: {$apiKey}"],
        CURLOPT_POSTFIELDS => json_encode(["phone_number" => $phone, "initial_context" => $context]),
    ]);
    $result = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $result;
}

Looking up the result

Use the returned workflow_run_id to poll for the call outcome:

bash

curl https://api.sysevo.io/api/v1/workflow/{workflow_id}/runs/{workflow_run_id} \
  -H "X-API-Key: YOUR_API_KEY"

Was this page helpful?

PreviousWorkflow Runs NextText Chat API