Dograh Integration

Dograh is an open-source, self-hostable voice AI platform for building phone agents. Plivo Audio Streaming bridges a phone call to a Dograh voice agent over a WebSocket.

How it works

Call flowDograh

Phone Call
PlivoAudio Stream
WebSocketWebSocket server
DograhVoice agent

Dograh handles the Plivo setup. It creates a Plivo Application and points the Application’s Answer URL to a Dograh endpoint, so hosting an Answer URL is not required. The Dograh endpoint hosts the WebSocket server that streams the call’s audio. On a call, Plivo requests the Answer URL of the auto-created Application and connects to Dograh’s WebSocket server, then streams the live call audio in both directions. Dograh’s voice agent transcribes the caller, generates a response, and streams the reply back as speech to Plivo over the same WebSocket.

Prerequisites

Requirement	Description
Plivo account	Sign up and copy the Auth ID and Auth Token from the Plivo console
Phone number	A voice-enabled Plivo number in E.164 format
Dograh	Dograh Cloud, or a self-hosted deployment reachable over HTTPS

Outbound call setup

For outbound calls, Dograh dials out with a caller ID from the Plivo configuration. No Plivo console changes are required.

Get the Plivo credentials

Add a Plivo configuration in Dograh

API
Console

Send the Plivo credentials to Dograh, authenticated with a Dograh API key.The application_id should be unset and Dograh creates a Plivo Application automatically.

config.auth_id, config.auth_token — the Plivo Auth ID and Auth Token.
is_default_outbound: true — makes this the default configuration for outbound calls.

Refer to Create a telephony configuration for all parameters.

curl -X POST "https://app.dograh.com/api/v1/organizations/telephony-configs" \
-H "X-API-Key: $DOGRAH_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "name": "Plivo",
  "is_default_outbound": true,
  "config": {
    "provider": "plivo",
    "auth_id": "<plivo_auth_id>",
    "auth_token": "<plivo_auth_token>"
  }
}'

const response = await fetch(
  'https://app.dograh.com/api/v1/organizations/telephony-configs',
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.DOGRAH_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Plivo',
      is_default_outbound: true,
      config: {
        provider: 'plivo',
        auth_id: '<plivo_auth_id>',
        auth_token: '<plivo_auth_token>',
      },
    }),
  },
);
console.log(await response.json());

import os
import requests

response = requests.post(
    "https://app.dograh.com/api/v1/organizations/telephony-configs",
    headers={"X-API-Key": os.environ["DOGRAH_API_KEY"]},
    json={
        "name": "Plivo",
        "is_default_outbound": True,
        "config": {
            "provider": "plivo",
            "auth_id": "<plivo_auth_id>",
            "auth_token": "<plivo_auth_token>",
        },
    },
)
print(response.json())

The response returns the configuration’s ID. Use it as the config_id when adding the default caller ID in the next step.

Add the default caller ID

Add a phone number to the saved configuration in E.164 format, for example +14150000001. This is the From number (the caller ID) for outbound calls.

API
Console

Add the number to the configuration and mark it as the default caller ID, authenticated with a Dograh API key.Use the config_id returned when the configuration is created, or shown on the saved configuration in Dograh.

address — the phone number in E.164 format.
is_default_caller_id: true — makes it the default caller ID for outbound calls.

Refer to Add a phone number for all parameters.

curl -X POST "https://app.dograh.com/api/v1/organizations/telephony-configs/<config_id>/phone-numbers" \
-H "X-API-Key: $DOGRAH_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "address": "+14150000001",
  "is_default_caller_id": true
}'

const configId = '<config_id>';

const response = await fetch(
  `https://app.dograh.com/api/v1/organizations/telephony-configs/${configId}/phone-numbers`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.DOGRAH_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      address: '+14150000001',
      is_default_caller_id: true,
    }),
  },
);
console.log(await response.json());

import os
import requests

config_id = "<config_id>"

response = requests.post(
    f"https://app.dograh.com/api/v1/organizations/telephony-configs/{config_id}/phone-numbers",
    headers={"X-API-Key": os.environ["DOGRAH_API_KEY"]},
    json={"address": "+14150000001", "is_default_caller_id": True},
)
print(response.json())

This number is not linked to a specific agent. Any agent can use this number as its caller ID when the call is started in Dograh.

Place an outbound call

Trigger a Dograh agent to call a destination number. The call dials from the default caller ID set above.

API
Console

Dograh dials the destination number and runs the agent on the call, authenticated with a Dograh API key.

workflow_uuid — in the URL path, the agent that places the call.
phone_number — the destination number in E.164 format.
telephony_configuration_id — optional, routes the call through a specific configuration instead of the default.

Refer to Trigger an outbound agent run for all parameters.

curl -X POST "https://app.dograh.com/api/v1/public/agent/workflow/<workflow_uuid>" \
-H "X-API-Key: $DOGRAH_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "phone_number": "+14155550123"
}'

const workflowUuid = '<workflow_uuid>';

const response = await fetch(
  `https://app.dograh.com/api/v1/public/agent/workflow/${workflowUuid}`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.DOGRAH_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ phone_number: '+14155550123' }),
  },
);
console.log(await response.json());

import os
import requests

workflow_uuid = "<workflow_uuid>"

response = requests.post(
    f"https://app.dograh.com/api/v1/public/agent/workflow/{workflow_uuid}",
    headers={"X-API-Key": os.environ["DOGRAH_API_KEY"]},
    json={"phone_number": "+14155550123"},
)
print(response.json())

On a self-hosted deployment, Dograh must be reachable at a public URL so Plivo can fetch the Answer URL and open the call’s media WebSocket. See Self-hosted setup for how to set this up.

Inbound call setup

For inbound calls, an external caller dials the Plivo number. The number must route to the Plivo Application that holds Dograh’s Answer URL, and it needs an inbound workflow that decides which agent answers.

Get the Plivo credentials

Add a Plivo configuration in Dograh

API
Console

Send the Plivo credentials to create the configuration and add the inbound number, authenticated with a Dograh API key.The application_id should be unset and Dograh creates a Plivo Application with the Answer URL already set.Refer to Create a telephony configuration and Add a phone number for all parameters.

# Create the configuration
curl -X POST "https://app.dograh.com/api/v1/organizations/telephony-configs" \
-H "X-API-Key: $DOGRAH_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "name": "Plivo",
  "config": {
    "provider": "plivo",
    "auth_id": "<plivo_auth_id>",
    "auth_token": "<plivo_auth_token>"
  }
}'

# Add the inbound number, using the config_id returned above
curl -X POST "https://app.dograh.com/api/v1/organizations/telephony-configs/<config_id>/phone-numbers" \
-H "X-API-Key: $DOGRAH_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "address": "+14150000001"
}'

const headers = {
  'X-API-Key': process.env.DOGRAH_API_KEY,
  'Content-Type': 'application/json',
};

// Create the configuration
await fetch('https://app.dograh.com/api/v1/organizations/telephony-configs', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Plivo',
    config: {
      provider: 'plivo',
      auth_id: '<plivo_auth_id>',
      auth_token: '<plivo_auth_token>',
    },
  }),
});

// Add the inbound number, using the config_id returned above
await fetch(
  'https://app.dograh.com/api/v1/organizations/telephony-configs/<config_id>/phone-numbers',
  {
    method: 'POST',
    headers,
    body: JSON.stringify({ address: '+14150000001' }),
  },
);

import os
import requests

headers = {"X-API-Key": os.environ["DOGRAH_API_KEY"]}

# Create the configuration
requests.post(
    "https://app.dograh.com/api/v1/organizations/telephony-configs",
    headers=headers,
    json={
        "name": "Plivo",
        "config": {
            "provider": "plivo",
            "auth_id": "<plivo_auth_id>",
            "auth_token": "<plivo_auth_token>",
        },
    },
)

# Add the inbound number, using the config_id returned above
requests.post(
    "https://app.dograh.com/api/v1/organizations/telephony-configs/<config_id>/phone-numbers",
    headers=headers,
    json={"address": "+14150000001"},
)

In Dograh, go to /telephony-configurations and select Add configuration.
Choose Plivo as the provider and enter the Auth ID and Auth Token.
Leave Application ID blank. Dograh creates a Plivo Application when the configuration is saved and sets its Answer URL automatically. To use an existing application instead, paste its Application ID.
Select Save Configuration.
Open the saved configuration and add the inbound phone number in E.164 format, for example +14150000001.

Link the number to the Plivo Application

Dograh creates the Plivo Application but does not attach numbers to it. The inbound number should be manually linked to the Plivo application.

API
Console

Update the Plivo number to point at the Dograh Application, authenticated with the Auth ID and Auth Token over Basic auth.

app_id — the Application ID from the Dograh saved configuration.

Refer to Update an Account Phone Number for all parameters.

curl -X POST "https://api.plivo.com/v1/Account/$PLIVO_AUTH_ID/Number/<number>/" \
-u "$PLIVO_AUTH_ID:$PLIVO_AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
  "app_id": "<dograh_application_id>"
}'

const authId = process.env.PLIVO_AUTH_ID;
const authToken = process.env.PLIVO_AUTH_TOKEN;
const authHeader = 'Basic ' + Buffer.from(`${authId}:${authToken}`).toString('base64');

const response = await fetch(`https://api.plivo.com/v1/Account/${authId}/Number/<number>/`, {
  method: 'POST',
  headers: {
    'Authorization': authHeader,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    app_id: '<dograh_application_id>',
  }),
});
console.log(await response.json());

import os
import requests

auth_id = os.environ["PLIVO_AUTH_ID"]
auth_token = os.environ["PLIVO_AUTH_TOKEN"]

response = requests.post(
    f"https://api.plivo.com/v1/Account/{auth_id}/Number/<number>/",
    auth=(auth_id, auth_token),
    json={"app_id": "<dograh_application_id>"},
)
print(response.json())

Sign in to the Plivo console.
Navigate to Phone Numbers → Your Numbers and open the inbound number.
Set its Application to the dograh-<random> application shown on the Dograh saved configuration, then save the number.

Assign an inbound workflow

Each inbound number needs an inbound workflow, which is the agent that answers calls to the number.

API
Console

Update the phone number in Dograh to set its inbound workflow, authenticated with a Dograh API key.

inbound_workflow_id — the workflow that answers calls to the number.
clear_inbound_workflow: true — removes the workflow later. On its own, inbound_workflow_id: null is treated as no change.

Refer to Update a phone number for all parameters.

curl -X PUT "https://app.dograh.com/api/v1/organizations/telephony-configs/<config_id>/phone-numbers/<phone_number_id>" \
-H "X-API-Key: $DOGRAH_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "inbound_workflow_id": <workflow_id>
}'

const configId = '<config_id>';
const phoneNumberId = '<phone_number_id>';
const inboundWorkflowId = 123;

const response = await fetch(
  `https://app.dograh.com/api/v1/organizations/telephony-configs/${configId}/phone-numbers/${phoneNumberId}`,
  {
    method: 'PUT',
    headers: {
      'X-API-Key': process.env.DOGRAH_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ inbound_workflow_id: inboundWorkflowId }),
  },
);
console.log(await response.json());

import os
import requests

config_id = "<config_id>"
phone_number_id = "<phone_number_id>"
inbound_workflow_id = 123

response = requests.put(
    f"https://app.dograh.com/api/v1/organizations/telephony-configs/{config_id}/phone-numbers/{phone_number_id}",
    headers={"X-API-Key": os.environ["DOGRAH_API_KEY"]},
    json={"inbound_workflow_id": inbound_workflow_id},
)
print(response.json())

Receive an inbound call

Once the workflow is saved, calls to this number are answered by the assigned agent.

A single Plivo configuration can hold multiple phone numbers, each with its own Inbound workflow.

Self-hosted setup

The Plivo integration works the same on Dograh Cloud and on a self-hosted instance. The only difference is that Plivo has to reach the self-hosted instance directly, so it needs a public HTTPS address. Dograh handles this automatically. Its self-hosting guide starts the whole stack with a single Docker command, and this command brings up a Cloudflare tunnel that exposes the instance at a public HTTPS URL. This default tunnel needs no Cloudflare account or token but the tunnel’s subdomain changes each time it restarts. Dograh uses the URL as the base of the Answer URL that Plivo fetches, for example https://<random>.trycloudflare.com/api/v1/telephony/inbound/run. For a stable hostname, run a named Cloudflare tunnel. This requires a Cloudflare account, and the same guide walks through the setup. Once Dograh is reachable at its public URL, the outbound and inbound setup is identical to Dograh Cloud.

Troubleshooting

Issue	Solution
Authentication failed	Confirm the Auth ID and Auth Token match the values in the Plivo console.
Inbound call is not answered	Confirm the number is linked to the Plivo Application configured in Dograh, the number has an inbound workflow assigned, and the Answer URL was set without a warning on save.
Call connects but has no audio	The bundled Docker tunnel handles reachability automatically. On a self-hosted custom-domain deployment, confirm Dograh is reachable at its public URL per Dograh’s self-hosting guide.
Webhook signature validation failing	Confirm the Auth Token in Dograh matches the Plivo console and that no proxy rewrites the inbound request.

Plivo Audio Streaming

How Plivo streams call audio over a WebSocket.

Dograh

The open-source Dograh voice AI platform.

Dograh Plivo docs

Dograh’s own Plivo configuration reference.

Concepts

Integration Guides

Workflows

Deploy

Reference

Dograh Integration

How it works

Prerequisites

Outbound call setup

Get the Plivo credentials

Add a Plivo configuration in Dograh

Add the default caller ID

Place an outbound call

Inbound call setup

Get the Plivo credentials

Add a Plivo configuration in Dograh

Link the number to the Plivo Application

Assign an inbound workflow

Receive an inbound call

Self-hosted setup

Troubleshooting

Plivo Audio Streaming

Dograh

Dograh Plivo docs

​How it works

​Prerequisites

​Outbound call setup

Get the Plivo credentials

Add a Plivo configuration in Dograh

Add the default caller ID

Place an outbound call

​Inbound call setup

Get the Plivo credentials

Add a Plivo configuration in Dograh

Link the number to the Plivo Application

Assign an inbound workflow

Receive an inbound call

​Self-hosted setup

​Troubleshooting

​Related

Plivo Audio Streaming

Dograh

Dograh Plivo docs

How it works

Prerequisites

Outbound call setup

Inbound call setup

Self-hosted setup

Troubleshooting

Related