Outbound calling

Configure outbound calls for appointment reminders, follow-ups, and notifications

PolyAI supports outbound calling for appointment reminders, follow-ups, and automated notifications.

Prerequisites

• An active PolyAI project
• Outbound calling enabled (contact your PolyAI representative)
• A phone number configured for outbound calls

Outbound calling requires configuration by PolyAI. Contact your account manager or [e-mail] to enable this feature.

Outbound calling methods

Outbound Calling API

Programmatically trigger calls via REST API

SIP integration

Route outbound calls through your SIP infrastructure

Using the Outbound Calling API

The Outbound Calling API lets you programmatically trigger calls and monitor their status:

• Appointment reminders - Call customers before scheduled appointments
• Follow-up calls - Re-engage customers after specific events
• Notifications - Deliver time-sensitive information via voice
• Campaigns - Run proactive outreach at scale

Quick start

1. Obtain your connector authentication token from your PolyAI representative

2. Use the regional API endpoint matching your deployment:

   • US: https://api.us-1.platform.polyai.app
   • UK: https://api.uk-1.platform.polyai.app
   • EUW: https://api.euw-1.platform.polyai.app

3. Trigger a call:

curl -X POST https://api.us-1.platform.polyai.app/api/v1/{account_id}/{project_id}/outbound-call/trigger \
  -H "X-CONNECTOR-ID: YOUR_CONNECTOR_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "[phone]",
    "metadata": {
      "customer_name": "John",
      "appointment_time": "2:00 PM"
    }
  }'

4. Monitor call status using the returned conversation_id:

Call status data is retained for approximately 2 hours after the call ends. Poll and store status data before it expires if you need it longer.

curl -X GET "https://api.us-1.platform.polyai.app/api/v1/{account_id}/{project_id}/outbound-call/status/{conversation_id}" \
  -H "X-CONNECTOR-ID: YOUR_CONNECTOR_ID"

For complete API documentation, see the Outbound Calling API reference.

SIP-based outbound calling

If you’re using a SIP integration, you can configure outbound calls through your existing telephony infrastructure. This method allows:

• Custom SIP header injection for the outbound leg
• Integration with your contact center platform
• Routing through your preferred carrier

When using custom SIP handoffs, you can specify the outbound endpoint in your function:

return {
    "handoff": True,
    "outbound_caller_id": conv.caller_number,
    "outbound_endpoint": "YOUR_OUTBOUND_ENDPOINT_NAME"
}

For detailed SIP configuration, see the Custom SIP integration guide.

Twilio-based outbound calling

If you’re integrated with Twilio, outbound calls can be routed through your Twilio account. This leverages your existing Twilio infrastructure and phone numbers.

Contact your PolyAI representative to configure Twilio-based outbound calling for your project.

Best practices

• Validate phone numbers - Use E.164 format (e.g., [phone])
• Respect time zones - Schedule calls during appropriate hours for the recipient
• Handle failures - Implement retry logic with exponential backoff
• Pass context via metadata - Include customer information to personalize conversations
• Monitor outcomes - Track delivery status for optimization

Call status tracking

When using the API, you can track call progress through these statuses:

Status	Description
queued	Call queued for processing
ringing	Call is ringing
in-progress	Call is active
completed	Call ended successfully
failed	Call failed to connect
no-answer	Call was not answered
busy	Destination was busy

Next steps

API reference

Complete API documentation

Trigger a call

API endpoint to initiate calls

Check call status

Monitor call progress

SIP integration

Configure SIP-based calling