Skip to navigation

Voice Proactive Outreach

Overview

Voice Proactive Outreach lets your AI Agent call an end user by phone. Your systems start the call. When a person answers, the Agent says the opening line that you write, then runs the Playbook that you link. If you link no Playbook, the call starts with your Greeting.

You can start a call in two ways:

  • From your system, with the Conversations API. Your system sends a request to Ada. Ada places the call over your own outbound SIP trunk, so your carrier dials the end user.
  • From your contact center dialer, with a SIP INVITE. Your dialer places the call. When a person is on the line, the dialer sends the call to Ada.

Ada turns on Voice Proactive Outreach for each AI Agent after your organization signs a contract addendum. To get access, contact your Ada team.

Limitations

Voice Proactive Outreach has the following constraints:

  • No voicemail. If your AI Agent detects an answering machine, it will end the call and will not leave a voicemail.
  • No retries. Ada does not call again after a call fails or is not answered.
  • One call for each trigger. Each request or SIP INVITE starts one call. You cannot schedule calls or upload a list of phone numbers.
  • The Conversations API option needs your own outbound SIP trunk. Ada does not place these calls from an Ada phone number. See Set up your outbound SIP trunk.
  • The dialer option works over SIP only. Custom SIP headers cannot cross a phone network (PSTN) connection. A call that your dialer sends to an Ada phone number never carries them.
  • Call status webhooks cover the Conversations API option only. Ada only sends v1.proactive_call webhooks for calls triggered using the Conversations API. It does not provide these webhook events for calls triggered using your dialer.
  • Handoffs on Conversations API calls go out over your trunk. A Handoff to a phone number or a SIP address uses your trunk and its caller ID. A Dialpad Handoff does not work on these calls. UUI headers and phone extensions are not passed on.
  • A conversation exists only after a person answers. A call that fails, is not answered, or reaches an answering machine does not show in the Conversations view.

Use cases

The following scenarios show common applications for Voice Proactive Outreach:

  • Call an end user about an open support case. Pass the case ID, so the Playbook can look up the status of the case.
  • Call an end user about an order or a delivery. Pass the order ID and the delivery date, so the Agent can confirm the details.
  • Let your contact center dialer place outbound calls, and send each answered call to the AI Agent.

Capabilities & configuration

Each Voice Proactive Outreach holds the settings for one type of call. Your system or your dialer names it by its Proactive ID when it starts a call.

Settings

The settings of a Voice Proactive Outreach control how each call starts.

SettingDescription
ChannelSelect Voice. You cannot change the channel after you save.
NameThe name of the item. Use up to 80 characters, with at least one letter or number. Each Proactive Outreach item needs a different name.
Default languageThe language of the call when the trigger does not specify one. The list shows your AI Agent’s default language and the translated languages that Voice supports.
PlaybookThe Playbook that runs when a person answers. Only active Playbooks are listed. Select None (Greeting) to start the call with your Greeting. If the linked Playbook becomes inactive, calls start with your Greeting.
Opening lineOptional. The exact words that the end user hears when they answer, before the Playbook starts. Use it for your business’s registered name and for the AI disclosures and recording notices that the law requires. Write it in the default language of your AI Agent, up to 250 characters. The field is available when a Playbook is selected. See Opening line.
Proactive IDA read-only ID that Ada assigns when you save. Your system or your dialer sends it to start a call.
Compliance attestationA check box that you must select before the item can be active.
Active toggleCalls are placed only while the Voice Proactive Outreach is active.

Opening line

The opening line is the first thing the end user hears when they answer. It gives every call a fixed start: the AI Agent says the exact words that you write, before the Playbook runs. The line does not depend on how the Playbook begins, and it plays before the Playbook’s first step is ready.

Use the line for the notices that must come first on every call. Include your business’s registered name, along with any AI disclosures or recording notices required by law. See Compliance responsibilities.

The line also removes the silence after the answer. The Agent waits for the end user to say hello, or for 2 seconds, then says the line. The Playbook’s first step is prepared in the meantime and runs after the line. Do not greet the end user again in that step. The line is spoken the same way on both trigger options, and it is the first message in the conversation transcript.

Write the line once, in the default language of your AI Agent. When you save, the Agent translates it into each other language that it speaks on Voice. In the Opening line section, select a language to read its translation. Click Modify translation to write your own text for that language. Click Remove manual translation to go back to the automatic text. If a translation is not ready when a call starts in that language, the Agent says the line in the default language.

The line follows these rules:

  • Up to 250 characters. A translation that you write yourself can have up to 500 characters.
  • No variables. The line is the same for every call.
  • No markup. The characters < and { are not allowed.
  • Only with a Playbook. If you clear the Playbook, the line is kept but not spoken.

A change to the line applies to calls that start after you save.

Compliance responsibilities

Your organization owns the legal side of every call. Your organization is responsible for making sure that every call complies with applicable laws and with your agreement with Ada. That includes:

  • Obtaining consent
  • Calling only during permitted hours
  • Honoring do-not-call (DNC) and suppression lists
  • Disclosing call recording
  • Disclosing that the caller is an AI
  • Honoring opt-out requests

Ada does not provide a do-not-call list, suppression lists, calling-hours enforcement or opt-out processing. Check these in your own systems before you start each call.

Ada is not responsible for deciding whether a specific call may be placed. Select the Compliance attestation check box before you enable the Active toggle. If you clear the check box, the Voice Proactive Outreach becomes inactive. The Conversations API also refuses a call for an item without the attestation.

Trigger options

The two trigger options differ in who dials the end user and in what Ada reports back.

Conversations APIContact center dialer
Who dialsYour outbound SIP trunk, when Ada asks it toYour dialer
Caller IDThe caller ID that your trunk presentsThe caller ID of your dialer
Answering machine detectionAdaYour dialer
How you pass contextmetadata in the requestX-Ada-Metadata-<name> SIP headers
Call status webhooksYesNo
What you set upYour outbound SIP trunkYour SIP connection to Ada

Quick start

Create a Voice Proactive Outreach, then start a call with the Conversations API. Before you start, Ada must turn on Voice Proactive Outreach for your AI Agent, and you must set up your outbound SIP trunk. For more detail, see Implementation & usage.

To create a Voice Proactive Outreach and start a call:

1

Go to Config > AI AGENT > Outreach.

2

Click New Proactive Outreach. If you have no Proactive Outreach items yet, click Create a Voice Proactive Outreach.

3

In the Channel section, select Voice.

4

Enter a Name. Optionally, select a Default language and a Playbook, and write an Opening line.

5

In the Compliance attestation section, select the check box.

6

Enable the Active toggle, then click Save.

The Voice Proactive Outreach opens, and the Proactive ID field shows its ID.

7

Send a POST /v2/conversations/proactive/ request with the Proactive ID and the phone number of the end user. See Start a call from your system.

Implementation & usage

Set up the trigger option that you use, pass context to the Playbook, and track each call.

Set up your outbound SIP trunk

A call that you start with the Conversations API goes out over your own outbound SIP trunk. Your carrier dials the end user. You enter the trunk settings in the dashboard, place a test call, then turn the trunk on.

The Outbound calling section shows on the Voice page after Ada turns on Voice Proactive Outreach for your AI Agent. Only an owner or an admin can view and change it. If the section does not show, contact your Ada team.

Your AI Agent needs a voice phone number before you can enter the trunk settings. Until it has one, the section shows only this message: “Outbound calling appears here once this AI Agent has a voice phone number.” See Voice onboarding.

Prepare the following on your trunk:

  • A termination endpoint. The trunk accepts INVITEs from Ada for sip:+<E.164 number>@<your host>. A trunk that accepts inbound calls does not prove that outbound calls work, because trunks are directional.
  • A way for the trunk to trust Ada. Choose one:
    • Digest credentials: a username and a password for Ada. Use a password of 12 to 128 letters and digits.
    • IP allowlist: allow the Twilio SIP signaling ranges on UDP and TCP port 5060 and TLS port 5061: 54.172.60.0/30 (Virginia) and 54.244.51.0/30 (Oregon) in North America, 54.171.127.192/30 (Ireland) and 35.156.191.128/30 (Frankfurt) in Europe. Also allow the media range 168.86.128.0/18 on UDP ports 10000 to 60000.
  • Outbound service to the countries that you call.
  • A caller ID that your trunk may present. Ada presents it on each call. Your carrier decides what the end user sees.
  • No route back to Ada. Your trunk must not send calls for the recipient numbers back to your Ada SIP domain.
  • A test phone number that Ada can call.

The trunk has these requirements:

  • The termination host is a public host name or IP address. A private IP address is not supported.
  • The trunk is not hosted by Twilio. Ada cannot place calls through a Twilio SIP domain (*.sip.twilio.com).
  • The transport is UDP, TCP or TLS. Secure media needs TLS.

To set up your outbound SIP trunk:

1

Go to Config > CHANNELS > Voice, then go to the Configuration tab.

2

In the Outbound calling section, enter the trunk settings. See the table after these steps.

3

Leave Use this trunk for outbound calls off, then click Save.

4

Under Test call, enter a Phone number to call in E.164 format, for example +14165550123. Click Test call, then answer the call.

The test call is a real call, and your carrier bills it. The call works while the trunk is off.

5

Read the result next to the Test call button. If the call did not connect, fix the setting that the message names, click Save and place another test call.

6

If your AI Agent sends text messages during calls, set the number that sends them. On the same tab, enter an SMS-capable Twilio number under Test phone number, or enable Use your own SMS channel.

Without one of these, your AI Agent cannot send a text during a call over your trunk. While Agent SMS is enabled and the number is missing, the Outbound calling section shows a warning.

7

Enable Use this trunk for outbound calls, then click Save.

The Outbound calling section has these settings:

SettingDescription
Termination hostThe SIP host name or public IP address of your carrier. Add a port when your trunk does not use the default port, for example sip.example.com:5061.
TransportUDP, TCP or TLS.
Encrypted mediaEncrypts the call audio toward your trunk. Available with TLS only.
AuthenticationSelect Username and password to use digest credentials, then enter the Username and the Password. Select IP allowlist to have the section list the signaling and media addresses to allow on your trunk.
Caller IDThe number in E.164 format that the end user sees. Your carrier must allow it on this trunk.
EdgeOptional. The Ada region that sends the call to your trunk. Select the edge closest to your trunk. With Automatic, calls come from the North American edges.
Use this trunk for outbound callsAda places calls over the trunk only while this toggle is enabled. When you turn it off, the settings stay saved.

The dashboard never shows a saved password. To keep it when you change other settings, leave the Password field empty.

The test call result shows one of these statuses:

StatusMeaning
Call connectedThe trunk works. Turn the trunk on.
Busy, No answer, Call failed or Call canceledThe call did not connect. The message under the result gives the likely cause, for example refused credentials or a caller ID that the trunk does not allow.
No result yetYour carrier reported no result within 2 minutes. Check the call with your carrier, or place another test call.
Call placedAda placed the call but cannot show its result. Give the call ID that the section shows to Ada support.

You can place up to 5 test calls in 5 minutes. After that, the section shows how many seconds to wait.

Turning on the trunk places no calls. Calls start when your system sends a request for an active Voice Proactive Outreach. To stop the calls, turn off Use this trunk for outbound calls and click Save. To delete the settings and the saved password, click Remove your SIP trunk from Ada.

Texts that your AI Agent sends during a call over your trunk go out from the Test phone number. Your trunk’s caller ID cannot send them. To send these texts from your own number, use your own SMS channel. See Send texts from your own SMS channel.

If no trunk is set up for your AI Agent, or the trunk is turned off, the request still returns 202. The call then fails with the client_configuration reason.

Start a call from your system

Your system sends one request for each call. Authenticate with an Ada API key. Replace example.ada.support with the domain of your AI Agent.

POST https://example.ada.support/api/v2/conversations/proactive/
Authorization: Bearer <API key>
Idempotency-Key: <unique key for this call>
Content-Type: application/json
{
"proactive_id": "<Proactive ID>",
"channel": "voice",
"recipient": { "phone_number": "+14155550123" },
"language": "en",
"metadata": { "order_id": "ORD-1042", "delivery_date": "2026-10-14" }
}

The request body has these fields:

FieldRequiredDescription
proactive_idYesThe Proactive ID of an active Voice Proactive Outreach.
channelYesMust be voice.
recipient.phone_numberYesThe phone number of the end user in E.164 format, for example +14155550123.
languageNoA language code that your AI Agent supports on Voice. If you omit it, the call uses the Default language of the Voice Proactive Outreach. If that is not set, the call uses the default language of your AI Agent.
metadataNoKey-value pairs that become metavariables when a person answers. See Pass context to the Playbook.

Send an Idempotency-Key header of 1 to 255 characters to retry safely. If you send the same key again within 90 days, Ada returns the first attempt with the Idempotent-Replayed: true header and does not call again.

A successful request returns 202 Accepted with the queued Proactive Attempt. The attempt has an id, a state of queued, and the values from your request. The response does not report the outcome of the call. To follow the call, use webhooks.

The end user’s phone rings for about 60 seconds. If nobody answers, the call fails with the no_answer reason.

The endpoint returns these errors:

StatusCause
400An unknown field, a phone number that is not valid E.164, a language that your AI Agent does not support on Voice, or metadata that breaks the rules.
404No Voice Proactive Outreach with this proactive_id exists for your AI Agent, or Voice Proactive Outreach is not turned on for it.
409Another request with the same Idempotency-Key is in progress. Retry the request.
422The Voice Proactive Outreach is not active, has no compliance attestation, is not on the voice channel, or would use a language that your AI Agent no longer supports on Voice.
429The request exceeds a rate limit. See Rate limits.

Answering machine detection

Ada detects who answers each call that you start with the Conversations API. Detection runs while the end user is already connected to the AI Agent, so the opening line is not delayed by it. The Playbook starts when detection completes, usually a few seconds after the answer.

  • If a person answers, the conversation starts and the Playbook runs.
  • If a voicemail system, an answering machine or a fax answers, Ada ends the call. The voicemail can record the first words of the opening line. No conversation is created, and Ada sends the v1.proactive_call.machine_detected webhook.
  • If detection cannot decide, the call continues as if a person answered.

Start a call from your contact center dialer

Your dialer places the call and runs its own answering machine detection. When a person is on the line, the dialer sends a SIP INVITE to your Ada SIP domain. The AI Agent then runs the Playbook.

Before you start, connect your SIP infrastructure to Ada. See Contact center integration.

Add these headers to the SIP INVITE:

HeaderRequiredDescription
X-Ada-Proactive-IdYesThe Proactive ID of an active Voice Proactive Outreach.
X-Ada-LanguageNoThe language of the call. If you omit it, or it matches no Voice language of your AI Agent, the call uses the Default language of the Voice Proactive Outreach.
X-Ada-Metadata-<name>NoOne header for each value that you pass. Each header becomes a metavariable named <name>.
INVITE sip:<your Ada SIP domain> SIP/2.0
X-Ada-Proactive-Id: <Proactive ID>
X-Ada-Language: en
X-Ada-Metadata-order_id: ORD-1042

Send the phone number of the end user in the SIP UUI header, as for every SIP call to Ada. If the UUI header has no phone number, Ada reads the number from the From header. If neither has a valid number, Ada rejects the call.

Use SIP from end to end. Custom headers cannot cross a phone network (PSTN) connection. If your dialer sends the call to an Ada phone number, the headers are lost and the call starts as an ordinary inbound call.

Ada answers the INVITE in one of these ways:

  • If the call can start, Ada connects it and the AI Agent starts the conversation.
  • If the Voice Proactive Outreach cannot start the call, Ada rejects the INVITE with SIP 404. For example, the item is inactive, has no compliance attestation, or the ID is not valid. Do not retry.
  • If Ada cannot take the call now, Ada answers with SIP 486 Busy Here. For example, your AI Agent is at its concurrent call limit. Your dialer can retry.

Pass context to the Playbook

Pass the details that the Agent needs for the call. When a person answers, each value becomes a metavariable that the Playbook can use.

  • Conversations API: each metadata key becomes a metavariable with the same name.
  • Contact center dialer: each X-Ada-Metadata-<name> header becomes a metavariable named <name>.

On both paths, the Agent also sets the proactive_id metavariable to the Proactive ID.

The values follow these rules:

Rulemetadata in the requestX-Ada-Metadata-<name> headers
Maximum count20 keys20 headers
Names1 to 64 letters, digits or underscores1 to 64 letters, digits, underscores or hyphens
ValuesStrings, numbers or booleans, up to 4 KB in total. Ada stores each value as text, so true becomes True.Text
Reserved namesA name that Ada sets itself, such as language, phone_number or email, returns 400.A name that Ada sets itself is dropped.

To use more data than you pass, send an identifier, for example an order ID. At the start of the Playbook, add a RUN step that runs an API tool with that identifier.

Your system can also update the profile of the end user during the call. Look up the details in your system with the identifier that you passed, then send PATCH /v2/end-users/{end_user_id} with the details in profile.metadata. The Agent reads each key as a metavariable in the same conversation. The v1.conversation.created webhook and GET /v2/conversations/{conversation_id}/ return the end_user_id of the call. The v1.proactive_call.answered event returns its conversation_id. See the End Users API.

Track calls with webhooks

Ada sends a webhook each time a call from the Conversations API reaches a new state. Add an endpoint in Config > PLATFORM > Webhooks. The v1.proactive_call events show there only for AI Agents that have Voice Proactive Outreach. For endpoint setup, see Webhooks.

EventSent when
v1.proactive_call.queuedAda accepts the request and queues the call.
v1.proactive_call.initiatedAda places the call with the carrier.
v1.proactive_call.answeredA person answers and the conversation exists.
v1.proactive_call.machine_detectedA voicemail system or an answering machine answers. No conversation is created.
v1.proactive_call.failedThe call ends without a person answering.

Each event has a type, a timestamp and a data object with these fields:

FieldDescription
proactive_attempt_idThe id that the Conversations API returned for the request.
proactive_idThe Proactive ID.
channelAlways voice.
statequeued, initiated, answered, machine_detected or failed.
recipient.phone_numberThe phone number of the end user.
languageThe language of the call.
metadataThe metadata from the request.
conversation_idThe ID of the conversation. It is null until a person answers.
failure_reasonWhy the call failed. It is null unless state is failed.
created_atWhen Ada accepted the request.
updated_atWhen the call reached state.
ai_agent_domainThe domain of the AI Agent that sent the event, for example acme.ada.support.

The failure_reason field has one of these values:

ValueMeaning
busyThe line was busy.
no_answerNobody answered.
rejectedThe call was declined or refused.
invalid_numberThe phone number cannot be called.
carrier_failureThe carrier could not connect the call.
capacity_exceededYour AI Agent reached its concurrent call limit. Retry with a new Idempotency-Key.
client_configurationYour AI Agent cannot place calls as configured. For example, no trunk is set up, or the trunk is turned off.
internal_errorAn error occurred at Ada.

Ada can add new values. Handle a value that you do not know as a failed call.

Events can arrive out of order. A call can reach answered, machine_detected or failed without an initiated event.

Best practices

These recommendations help each call reach the end user once and start with the right context:

  • Send an Idempotency-Key with every request. If a request times out, retry with the same key, so the end user gets one call only.
  • After a capacity_exceeded failure, retry with a new Idempotency-Key. The old key returns the failed attempt.
  • Keep the linked Playbook active. If it becomes inactive, calls start with your Greeting.
  • Put the name of your business and the required disclosures in the opening line. Do not repeat them in the Playbook’s first step.
  • Pass an identifier in metadata, then look up other details with an API tool at the start of the Playbook.
  • Track each call by its state and updated_at, not by the order in which events arrive.

These features work with Voice Proactive Outreach: