Triggering calls

A voice agent places outbound calls when something asks it to. You can trigger calls from your own systems with the call trigger API, or from a Robylon workflow.

The endpoint and a sample payload for each agent are in the voice agent builder under Set Call Triggers via API.

How do I trigger a call with the API?

Send a POST request with the agent’s ID, the phone number and the customer’s details, authenticated with your API key.

curl -X POST https://api.robylon.ai/voice/agent/test-call/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "phone_number": "+15551234567",
    "variables_info": {
      "customer_name": "Alex",
      "order_id": "10234"
    }
  }'

• Endpoint: POST https://api.robylon.ai/voice/agent/test-call/. Despite the name, this endpoint places real calls. It is shown under API Endpoint in the agent. https://api.robylon.ai/voice/agent/trigger-call/ works the same way.
• Authentication: your workspace API key, in an X-API-Key header or as Authorization: Bearer YOUR_API_KEY. Create keys in Settings → Data & Developer → API Keys, see API keys.
• Agent ID: shown under Agent ID in Set Call Triggers via API. Use Copy sample payload to start from a payload that already lists your agent’s variables.

What can I send in the request?

A full example:

{
  "agent_id": "YOUR_AGENT_ID",
  "phone_number": "+15551234567",
  "variables_info": {
    "customer_name": "Alex",
    "order_id": "10234"
  },
  "call_timing": {
    "start": { "hour": 9, "minute": 0 },
    "end": { "hour": 18, "minute": 0 },
    "timezone": "America/New_York",
    "queue_requests": true
  },
  "voice_retry_config": {
    "should_retry": true,
    "max_retries": 3,
    "retry_in_minutes": 60
  },
  "key_terms": ["Acme"],
  "include_variable_key_terms": false,
  "is_test_call": false
}

How do retries work?

Robylon calls again after a call fails, is not answered or is busy, when both of these are set in the request:

• voice_retry_config.should_retry is true, and
• call_timing.queue_requests is true.

Without queue_requests, the call is dialled once and not retried. Robylon waits retry_in_minutes between attempts.

• max_retries is the total number of dials including the first one. With max_retries: 3, the customer is called at most three times.
• A single request is never dialled more than 15 times, whatever you set.
• A retry that would fall outside the call_timing window is moved to the start of the next window.
• A request still waiting for a retry 48 hours after it was created is cancelled.
• Inbound calls are never retried.

What does the API return?

A successful request returns 200 with:

{ "result": true }

This means the call was queued, not that it was answered. The call’s outcome appears in Robylon once it ends. Errors return 400 or 401 with an error message:

The API does not return a call ID. To act on the outcome, use post-call analysis: extracted values are saved on the call’s ticket, and a post-call workflow receives the call’s status, transcript, summary and recording. A webhook that posts each call’s result to your own URL is available on request, email support@robylon.ai.

Can I trigger calls in bulk?

There is no bulk endpoint. To call many people:

• Send one API request per person, or
• Use a workflow (below), which runs the voice agent each time its trigger fires.

How do I trigger calls from a workflow?

Add an AI agent step to a workflow, set Select Channel to Voice, and choose the agent under Select Voice AI Agent. The workflow’s trigger decides when calls are made.

In the step:

• Under Configure the variables used in the voice AI agent, map each of the agent’s variables to data from the trigger or earlier steps.
• Under Set Retry logic, switch on Do you want to retry the calls and set No. of times to retry, Interval between retries and Max time uptill retries.

Calls started from a workflow follow the agent’s Calling Hour Config, and retries only happen while Queue call requests outside calling hours is on. See Call settings.

After each try, the step fills variables such as {voice_call_status}, {voice_call_transcript}, {voice_call_duration}, {voice_call_summary}, {voice_call_count} and {voice_call_number} for later steps.

See Workflows and Triggers.