Outbound voice is where many teams first feel VOXBRIDGE in production: a CRM event fires, an API request places a call, and an AI agent delivers a script that adapts to answers. This tutorial walks through your first outbound call using the REST API—authentication, payload shape, idempotency, and webhook confirmation—so you can go from zero to hearing a test call on your mobile in under thirty minutes.
Prerequisites
Before you send traffic, complete setup in the VOXBRIDGE console at voxbridge.cc:
- Create a project and generate an API key with outbound scope.
- Verify a caller ID number permitted for your destination country.
- Attach an agent profile with voice, prompt, and any tools you need.
- Configure a webhook URL to receive
call.completedevents.
Full reference lives in our documentation; this article highlights the path most developers take on day one.
Authenticate every request
Use HTTPS and send your API key in the Authorization header as a Bearer token. Rotate keys from the dashboard if one leaks in a log aggregator. For local development, store secrets in environment variables—not committed .env files shared in chat.
Base URL for REST resources:
https://api.voxbridge.cc/v1/
Pin your integration to the version prefix shown in docs; we announce breaking changes there with migration notes.
Create an outbound call with POST
The outbound endpoint accepts JSON specifying who to dial, which agent to run, and optional variables injected into the prompt. A minimal body looks like this conceptually: destination E.164 number, agent_id, and a variables object for personalization such as customer name or appointment time.
Example fields you should plan for in production:
- to — callee phone in E.164 format (+14155551212).
- from — your verified outbound caller ID.
- agent_id — UUID from the Agents screen.
- variables — key-value pairs referenced as in prompts.
- metadata — opaque strings echoed in webhooks for CRM correlation.
Send the POST from curl, Postman, or your backend job runner. A 201 response includes call_id; persist it immediately in your database next to the CRM record you are automating.
Treat
call_idas your idempotency anchor. If your job retries, look up whether a call already exists for that CRM task before placing a second dial.
Handle responses, errors, and compliance
4xx errors usually mean validation problems: unverified caller ID, malformed number, or agent in draft state. 5xx errors warrant exponential backoff; do not hammer retries that could duplicate live calls if the first actually connected.
Respect quiet hours and consent flags stored in your CRM. The API will place the call when asked; your application layer must enforce policy. Pass a scheduled_at field when supported to queue off-peak dials instead of blocking your worker thread.
Confirm outcomes with webhooks
Your server should answer webhook deliveries within two seconds with HTTP 200, then process asynchronously. On call.completed, expect duration, disposition, transcript summary, recording URL, and the metadata you attached. Update CRM stage, mark tasks complete, or trigger a human follow-up when disposition is transfer_requested.
Verify signatures using the shared secret from the Integrations panel. Reject unsigned bodies in production. Log raw payloads temporarily in sandbox to debug mapping, then redact PII in application logs.
Test like production
Start with your own mobile as to. Run three scenarios: full completion, voicemail detection if enabled, and user hang-up mid-script. Listen for pacing, disclosure placement, and whether variables pronounced correctly—TTS sometimes needs phonetic hints for uncommon names.
Load-test with throttled concurrency only after business rules pass review. Carriers and recipients both punish burst dialing that looks like spam. VOXBRIDGE enforces rate limits documented on the pricing page; design queues accordingly.
Next steps after the first successful call
Wire your CRM or data warehouse to enqueue calls when opportunities hit stage “Demo scheduled” or invoices cross due dates. Add function tools so the agent can reschedule or capture email during the conversation. Compare advanced outbound features against other platforms on compare.
When you are satisfied in sandbox, promote the same agent version to production keys and monitor cost per completed minute against your pilot budget. Open a free tenant at signup if you have not already—the included minutes are enough to place dozens of test calls while you harden idempotency and webhook handlers. Hearing your API place a real conversation is the milestone everything else builds on.