mirror of
https://github.com/dograh-hq/dograh.git
synced 2026-06-07 07:55:16 +02:00
97 lines
No EOL
3.7 KiB
Text
97 lines
No EOL
3.7 KiB
Text
---
|
|
title: "API Trigger"
|
|
description: "Trigger outbound calls from external systems like n8n, Zapier, or your own backend"
|
|
---
|
|
|
|
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](/integrations/telephony/overview) — outbound calls will fail without one
|
|
- An [API key](/configurations/api-keys) 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 — one for the published agent and one 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. Once you publish your draft, both URLs run the same definition.
|
|
|
|
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 an optional `initial_context` object.
|
|
|
|
```bash
|
|
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"
|
|
}
|
|
}'
|
|
```
|
|
|
|
### Response
|
|
|
|
A successful request returns a `workflow_run_id` that you can use to [retrieve call details](/api-reference/calls/get-run), recordings, and transcripts.
|
|
|
|
```json
|
|
{
|
|
"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](/voice-agent/template-variables) — values enclosed in `{{` and `}}`.
|
|
|
|
For example, if your request includes:
|
|
```json
|
|
{
|
|
"phone_number": "+14155550100",
|
|
"initial_context": {
|
|
"user": {
|
|
"name": "John"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
You can reference the user's name in your prompt as `{{initial_context.user.name}}`.
|
|
|
|
See [Context & Variables](/core-concepts/context-and-variables) for more on how data flows through a call.
|
|
|
|
<Note>
|
|
For full endpoint details including all parameters and response fields, see the [API reference](/api-reference/calls/trigger).
|
|
</Note> |