API Trigger

The API Trigger node lets you initiate outbound calls to your voice agent programmatically. When you add an API Trigger node to your workflow, Dograh generates a unique endpoint URL that external systems can call to start a conversation. This is useful when you want to trigger calls from your own backend, a CRM, or workflow tools like n8n and Zapier.

Prerequisites

A configured telephony provider — outbound calls will fail without one
An API key for authentication

Finding your trigger URL

When you add an API Trigger node to your workflow, Dograh assigns it a unique UUID. The trigger node exposes two URLs that share this UUID:

A production URL for the published workflow
A test URL for the latest draft

You can copy either URL from the trigger node’s settings dialog.

POST https://your-dograh-instance/api/v1/public/agent/{uuid}        # Production
POST https://your-dograh-instance/api/v1/public/agent/test/{uuid}   # Test

If you are using the hosted version, replace your-dograh-instance with api.dograh.com.

Test vs production

Mode	URL	Runs
Production	`/api/v1/public/agent/{uuid}`	The published version of the agent.
Test	`/api/v1/public/agent/test/{uuid}`	The latest draft. Falls back to the published version if no draft exists.

Use the test URL while iterating on changes so production traffic continues to hit the published version. The production URL only executes a published workflow. If you update the workflow but do not publish it, the production trigger will continue to run the older published version. Once you publish your draft, both URLs run the same definition.

A common pitfall is editing the workflow, saving the draft, and then calling the production trigger URL expecting the new behavior. That will not work until you publish the workflow. Use the test URL to verify draft changes before publishing.

The request body, headers, and response shape are identical for both URLs.

Making a request

Authenticate by passing your API key in the X-API-Key header. The request body requires a phone_number and accepts optional initial_context, telephony_configuration_id, and from_phone_number_id fields.

curl -X POST https://your-dograh-instance/api/v1/public/agent/{uuid} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_your_api_key" \
  -d '{
    "phone_number": "+14155550100",
    "initial_context": {
      "customer_name": "Jane",
      "appointment_date": "March 15"
    }
  }'

curl -X POST https://your-dograh-instance/api/v1/public/agent/test/{uuid} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_your_api_key" \
  -d '{
    "phone_number": "+14155550100",
    "initial_context": {
      "customer_name": "Jane",
      "appointment_date": "March 15"
    }
  }'

Use the test URL when you want to verify draft changes before publishing.

Response

A successful request returns a workflow_run_id that you can use to retrieve run details, recordings, and transcripts.

{
  "status": "initiated",
  "workflow_run_id": 12345,
  "workflow_run_name": "WR-API-7823"
}

Error responses

Status	Cause
`400`	Telephony provider not configured, or call failed to initiate
`401`	Missing or invalid API key
`403`	API key does not have access to this agent
`404`	Trigger not found or not active

Initial context

initial_context is a JSON object containing any information you want your voice agent to access during the call. You can reference these values in your prompts using template variables — values enclosed in {{ and }}. For example, if your request includes:

{
    "phone_number": "+14155550100",
    "initial_context": {
        "user": {
            "name": "John"
        }
    }
}

You can reference the user’s name in your agent prompt as {{user.name}} — in Agent prompts, initial_context fields are referenced directly by name (not prefixed with initial_context.). See template variables for the exact syntax in prompts versus webhook payloads. See Context & Variables for more on how data flows through a call.

Override the greeting for one call

Pass greeting_override inside initial_context to replace the Start Call node’s saved greeting for one API-triggered call. A valid override takes precedence over the saved greeting. If you omit it, Dograh uses the saved greeting; if neither exists, the Start node follows its normal no-greeting behavior. For a text greeting:

{
  "phone_number": "+14155550100",
  "initial_context": {
    "greeting_override": {
      "type": "text",
      "text": "Hi, please confirm account {{account_id}}."
    }
  }
}

For a pre-recorded greeting, pass the recording’s string ID from the Recordings page:

{
  "phone_number": "+14155550100",
  "initial_context": {
    "greeting_override": {
      "type": "audio",
      "recording_id": "callback-welcome"
    }
  }
}

Dograh renders a text override after Pre-Call Data Fetch completes, so the override can reference variables returned by the fetch. The override follows the same playback restrictions as a saved greeting. In particular, static text greetings are not spoken by realtime speech-to-speech models; use an audio override for those configurations. Pre-Call Data Fetch can also return greeting_override. Because fetched context is applied after trigger context, a valid fetched override replaces one supplied by the trigger.

Choosing a telephony configuration and caller ID

By default, calls are placed through your organization’s default outbound telephony configuration. To route a specific call through a different configuration — for example, to dial out from a regional number — pass telephony_configuration_id in the request body.

{
  "phone_number": "+14155550100",
  "telephony_configuration_id": 42
}

The id is shown on each row in Telephony configurations (https://app.dograh.com/telephony-configurations for hosted or http://localhost:3010/telephony-configurations for local). The configuration must belong to the same organization as the API Trigger; otherwise the request returns 404. To use a specific caller ID from that configuration, also pass from_phone_number_id:

{
  "phone_number": "+14155550100",
  "telephony_configuration_id": 42,
  "from_phone_number_id": 84
}

from_phone_number_id is the ID of a phone number configured under the selected telephony configuration. The number must be active and belong to that configuration; otherwise the request returns 400. You can retrieve configured numbers with List phone numbers.

For full endpoint details including all parameters and response fields, see the API reference.

Getting started

Build your First Agent

Core Concepts

Configurations

Voice Agent Builder

Telephony

Integrations

Prerequisites

Finding your trigger URL

Test vs production

Making a request

Response

Error responses

Initial context

Override the greeting for one call

Choosing a telephony configuration and caller ID

​Prerequisites

​Finding your trigger URL

​Test vs production

​Making a request

​Response

​Error responses

​Initial context

​Override the greeting for one call

​Choosing a telephony configuration and caller ID

Prerequisites

Finding your trigger URL

Test vs production

Making a request

Response

Error responses

Initial context

Override the greeting for one call

Choosing a telephony configuration and caller ID