Telephony Integration

Connecting your agent to the phone network takes three steps:

Add a phone number: import one you own, or bring your own SIP trunk.
Create a routing rule: link the number to your agent.
Place a call: call the agent, or have it call out.

Deploy first. A routing rule only sends calls to the agent, so the agent must be running to answer them. Commit and deploy your agent before you test telephony.

1. Add a phone number

Import number
Bring your own SIP (BYOS)

Import a number you already own from a supported provider (Twilio or Plivo). The video uses Twilio.

Open Telephony

In the dashboard, open Telephony and select Add Number → Import Number.

Choose a provider

Select Twilio or Plivo.

Enter the details

Enter a Name For Phone Number, your provider credentials (Account SID and Auth Token for Twilio, or Auth ID and Auth Token for Plivo), and the phone number.

Import

Select Import Number. The number is active and ready to use.

Don’t have a number? Select Add Number → Buy Number to buy one in the dashboard.

Connect numbers from your own SIP trunk or carrier through an inbound and an outbound SIP gateway.

Dashboard
API

This video uses Telnyx as the SIP carrier. The steps are the same for any carrier.

Open SIP configuration

Open Telephony and select Add Number → Configure SIP.

Basic information

Enter a Name and add your phone numbers in E.164 format, for example +14155550100. Turn on Shared Gateway to use one gateway pair for all the numbers.

Inbound

Choose a SIP Region, then copy the Inbound Gateway URL into your carrier’s settings, so calls to your numbers reach Zero Runtime.

Outbound

Enter your carrier’s Outbound Gateway Address (for example sip.my-carrier.com), the Transport, and the SIP Username and SIP Password if your carrier needs them.

Activate

Optionally turn on Media Encryption, then select Save & Activate.

curl -X POST 'https://api.zeroruntime.ai/v2/sip/phone-numbers' \
  -H 'Authorization: YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Support SIP",
    "phoneNumbers": ["+14155550100"],
    "inbound": { "sipRegion": "auto" },
    "outbound": {
      "address": "sip.my-carrier.com",
      "sipRegion": "us002",
      "transport": "tls",
      "auth": { "username": "sip-user", "password": "s3cr3t" }
    }
  }'

See Create number with SIP gateways for every field.

2. Create a routing rule

A routing rule links your phone numbers to an agent:

Inbound: calls to the number are answered by the agent.
Outbound: the agent places calls from the number, one at a time or through batch calls.

You need your agent’s ID (for example ag_7l0yt8). Copy it from the chip next to Agent on the Agent tab, or with Copy Agent ID in the ⋯ menu.

Dashboard
API

Create the rule

Open Telephony → Routing Rules and select Create Routing Rule. Choose Inbound or Outbound, enter a Routing Rule Name, and select your phone numbers.

Add your agent

Under Agent Configuration, enter your agent’s ID in Agent Name or ID, then select Verify Agent ID.

Save

Select Create Rule.

You can also assign existing rules from the builder. On the Pipeline tab, select Phone Number, choose the rules, and select Assign.

Assigning a routing rule takes effect immediately and applies to the whole agent. It isn’t part of the draft and doesn’t need a commit.

Create a routing rule with your agent’s ID in agentId:

curl -X POST 'https://api.zeroruntime.ai/v2/sip/routing-rule' \
  -H 'Authorization: YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Support inbound",
    "type": "inbound",
    "phoneNumbers": ["+14155550100"],
    "agentId": "ag_7l0yt8"
  }'

type is inbound or outbound, and can’t be changed later.
phoneNumbers must already be on your account.

To point an existing rule at your agent, update only its agentId:

curl -X PATCH 'https://api.zeroruntime.ai/v2/sip/routing-rule/rr_8k2m1x' \
  -H 'Authorization: YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "agentId": "ag_7l0yt8" }'

See Create routing rule and Update routing rule for every field.

3. Place a call

Inbound
Outbound

Call your number from any phone. The agent answers with its welcome message.If the call isn’t answered, check that:

The agent is deployed.
The number has an inbound routing rule with your agent’s ID.
For BYOS, your carrier sends calls to the Inbound Gateway URL.

Have the agent call a number. The call uses the agent on your number’s outbound routing rule.

curl -X POST 'https://api.zeroruntime.ai/v2/sip/call' \
  -H 'Authorization: YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "sipCallFrom": "+14155550100",
    "sipCallTo": "+14155550199",
    "routingRuleId": "rr_2554md"
  }'

sipCallFrom is your number, and sipCallTo is the number to call. Both are in E.164 format.
Leave out routingRuleId to use the first outbound rule on sipCallFrom.

See Make an outbound call for every field. To call a list of numbers, use batch calls.

Get started

Agent

Pipeline

Tools and Knowledge Base

Telephony

Deployment and Observability

Version Control

1. Add a phone number

2. Create a routing rule

3. Place a call

​1. Add a phone number

​2. Create a routing rule

​3. Place a call

1. Add a phone number

2. Create a routing rule

3. Place a call