API reference / Outreach

Voice broadcasts and AI calls

Two routes ring one person's phone. POST /voice-broadcast plays a message and can act on a key press. POST /ai-broadcast hands the call to one of your AI agents. The recipient fields, foreign_id, callback_url and merge fields work the same on every send; see Sending basics.

Both answer 202. Each call's result arrives on contact.rvm.status, with campaign_type set to voice_broadcast or ai_broadcast, and on your callback_url. Outside the contact's calling hours the call is held and retried for up to 3 days; see Calling hours.

A 202 means accepted, not delivered. The result of each call arrives on the contact.rvm.status webhook. Calling hours, the contact frequency limit and retries are explained in Send lifecycle. What each reason_code means, and what to do about it, is in Outcomes and what to do.

Choose the phone line

Both routes call from a phone line on your account. The recipient sees one of its numbers, and return calls and texts reach that line, where its routing applies: forward, queue, voicemail or whatever you set up.

Field	Type	Required	Description
`phone_line_id`	string	No	The phone line to call from. Leave it out to call from your default phone line. List lines with `GET /phone/public/lines`.
`caller_id`	string	BYOC only	Your carrier's number in E.164, shown as the caller ID exactly as given. Only bring-your-own-carrier (BYOC) accounts can set it; on other accounts it's ignored. If you send `phone_line_id` too, the line wins.

If you leave out phone_line_id and your account has no default phone line, the send fails with 4010.

When a voicemail system answers, the result has proof of delivery: a recording of the whole call, from the greeting through your message, available for 7 days. A full or unset mailbox (4002 or 4001) has one too, of the carrier's announcement. An AI call a person answered has one when the agent's Record calls setting is on.

Send a voice broadcast

POST /voice-broadcast. With OAuth, the token needs the voice:send scope. The call plays one message to a person who answers and another to an answering machine. A key press can transfer the call, record interest, or opt the number out.

Give at least one message, as text to speech (tts_on_* with voice_id) or as a recording (media_on_*):

Field	Type	Required	Description
`tts_on_speech` or `media_on_speech`	string	One message	Played when a person answers
`tts_on_beep` or `media_on_beep`	string	One message	Played to an answering machine
`tts_on_transfer` or `media_on_transfer`	string	No	Played before a transfer
`tts_on_confirm` or `media_on_confirm`	string	No	Played after the confirm key
`tts_on_opt_out` or `media_on_opt_out`	string	No	Played after the opt-out key
`voice_id`	string	With any `tts_on_*`	The voice for every `tts_on_*` field. List voices with `GET /voice/public/voices`.

media_on_* fields take a media_id from GET /media/public/media. The tts_on_* fields support merge fields.

Then set the phone line, keys and ringing:

Field	Type	Required	Description
`transfer_digit`	integer	No	Key, 0 to 9, that transfers the call. Needs `transfer_ivr_id` or `transfer_to`.
`transfer_ivr_id`	string	No	The phone line that takes transfers. Use this when you can.
`transfer_to`	string	No	A number in E.164 that takes transfers when there's no `transfer_ivr_id`
`confirm_digit`	integer	No	Key, 0 to 9, that records interest
`opt_out_digit`	integer	No	Key, 0 to 9, that adds the number to your do-not-contact list
`amd_enabled`	boolean	No	Detect answering machines and play the `*_on_beep` message after the greeting. Default `false`.
`max_ring_seconds`	integer	No	How long to wait for an answer, in seconds. Default 30.

curl -X POST https://api-v2.dropcowboy.com/voice-broadcast \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Idempotency-Key: 3c8f1a6e-9b2d-4e7a-b5c1-8d3f6a2e9b14" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+13125550142",
    "phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
    "voice_id": "7d2a9e4b-1c6f-4b3a-8e5d-2f9c7a1b4e63",
    "tts_on_speech": "Hi, this is Example Dental confirming your visit tomorrow at 10 AM. Press 1 to talk to us now.",
    "tts_on_beep": "Hi, this is Example Dental. Please call us back to confirm your visit.",
    "transfer_digit": 1,
    "transfer_ivr_id": "9a4c2e7b-1d5f-4b8a-a3e6-2f7c9b1d4e85",
    "amd_enabled": true
  }'

These problems fail the send before the call is placed:

Code	Cause	What to do
`4010`	No `phone_line_id`, and your account has no default phone line	Send `phone_line_id`, or set a default line.
`3001`	A `media_on_*` value isn't one of your media files	Check the id with `GET /media/public/media`.
`3002`	`tts_on_*` without `voice_id`	Add `voice_id`.
`3020`	A key isn't a single digit from 0 to 9	Fix the digit.
`3030`	`transfer_ivr_id` isn't a valid phone line id	Use an id from `GET /phone/public/lines`.
`3031`	`transfer_digit` with no `transfer_ivr_id` and no `transfer_to`	Add a transfer destination.
`3011`	`transfer_to` isn't in E.164	Send it with `+` and the country code.

Send an AI call

POST /ai-broadcast. With OAuth, the token needs the voice:send scope. One of your published AI agents handles the call. Build and publish the agent first; see AI agents.

Field	Type	Required	Description
`agent_id`	string	Yes	A published, active agent. List yours with `GET /agents/public/agents`.
`phone_line_id`	string	No	The phone line to call from; see Choose the phone line. Defaults to your default phone line.
`voice_ids`	string[]	No	Voices to use instead of the agent's own voice
`voice_rotation`	string	No	`sticky` or `round_robin`, for choosing among several `voice_ids`

curl -X POST https://api-v2.dropcowboy.com/ai-broadcast \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Idempotency-Key: 7b2e9d4a-6c1f-4a8e-9d3b-5f1a7c4e2d96" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+13125550142",
    "phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
    "agent_id": "4c8e2a6f-3b9d-4e1a-9c7b-5d2f8a3e6b19",
    "callback_url": "https://hooks.example.com/dropcowboy/outcome"
  }'

Each call also sends one ai_agent.* webhook with the conversation's outcome. See AI agents.

Reason	Code	What to do
`No Agent`	`3999`	The `agent_id` is missing or isn't one of your agents. Check the id.
`Agent Is Draft`	`3999`	Publish the agent, then send again.
`Agent Not Active`	`3999`	Activate the agent, then send again.
`No Caller ID`	`4010`	No `phone_line_id`, and your account has no default phone line. Send `phone_line_id`, or set a default line.
`Invalid voice_ids` or `Invalid voice_rotation`	`3002`	Send `voice_ids` as a list of voice ids, and `voice_rotation` as `sticky` or `round_robin`.

Common problems

The call failed with 4010. It named no phone_line_id and your account has no default phone line. Send phone_line_id, or set a default line.
Nobody heard the message on an answering machine. Set amd_enabled to true and give a *_on_beep message.
The key press didn't transfer. Check transfer_digit matches what the message tells people to press, and that the transfer destination is set.
The AI call failed with Agent Is Draft. Publish the agent first.

For more symptoms and fixes, see Troubleshooting. Every code is in Outcomes.

While Drop Cowboy provides tools to support compliance efforts, customers remain solely responsible for obtaining proper consent, maintaining opt-out lists, and complying with all federal and state telemarketing regulations. Consult with your legal counsel to ensure your specific use case and consent mechanisms comply with applicable laws.

Voice broadcasts and AI calls

Choose the phone line

Send a voice broadcast

Send an AI call

Common problems

Code samples