Make a Voice Call

Initiate an outbound voice call. When the recipient answers, AfriRoute fetches your answer_url to retrieve the NCCO that controls the call flow.

📡 Endpoint

POST /v1/voice/call

📥 Parameters

Field	Type	Required	Description
from	string	Yes	Caller ID in E.164 format
to	string	Yes	Recipient number in E.164 format
answer_url	string	No	URL returning the NCCO (IVR/TwiML) call flow
event_url	string	No	URL to receive call lifecycle events
agent_id	string	No	Call-center agent to associate with the call
record	boolean	No	Record the call (default false)

🚀 Quick Start

curl -X POST https://api.afriroute.ai/api/v1/voice/call \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+251116000000",
    "to": "+251911234567",
    "answer_url": "https://yourapp.com/voice/answer",
    "event_url": "https://yourapp.com/voice/events"
  }'

💻 Code Samples

const response = await fetch('https://api.afriroute.ai/api/v1/voice/call', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer $AFRIROUTE_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: '+251116000000',
    to: '+251911234567',
    answer_url: 'https://yourapp.com/voice/answer',
    record: true
  })
});

const data = await response.json();
console.log(data.call_id); // call_abc123

import requests

response = requests.post(
    'https://api.afriroute.ai/api/v1/voice/call',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'},
    json={
        'from': '+251116000000',
        'to': '+251911234567',
        'answer_url': 'https://yourapp.com/voice/answer'
    }
)
print(response.json()['call_id'])

📊 Response

{
  "call_id": "call_abc123",
  "status": "initiated",
  "started_at": "2026-05-28T10:30:00Z"
}

🎙️ The Answer URL

When the call is answered, AfriRoute issues a POST to your answer_url. Return an NCCO array:

app.post('/voice/answer', (req, res) => {
  res.json([
    { action: 'talk', text: 'Hello! This is a call from AfriRoute.' },
    {
      action: 'connect',
      endpoint: [{ type: 'phone', number: '+251911111111' }]
    }
  ]);
});

🔎 Check Call Status

GET /v1/voice/call/:call_id

{
  "call_id": "call_abc123",
  "status": "completed",
  "from": "+251116000000",
  "to": "+251911234567",
  "duration": 42,
  "started_at": "2026-05-28T10:30:00Z",
  "ended_at": "2026-05-28T10:30:42Z"
}

🔔 Call Events

If event_url is set, AfriRoute posts each transition:

app.post('/voice/events', (req, res) => {
  const { call_id, status, duration } = req.body;
  console.log(`Call ${call_id}: ${status} (${duration ?? 0}s)`);
  res.sendStatus(200);
});

Event	Description
started	Call initiated
ringing	Recipient ringing
answered	Call answered
completed	Ended normally
failed / busy / timeout	Not connected

💡 Best Practices

• Use a registered caller ID in from for better answer rates.
• Return NCCO fast — slow answer_url responses can drop the call.
• Set event_url to log outcomes and durations for billing reconciliation.
• Respect local calling hours to improve pickup rates.
• Enable record only with consent where required by law.

⚠️ Error Handling

try {
  await makeCall(payload);
} catch (error) {
  if (error.code === 'INVALID_NUMBER') {
    console.error('Check E.164 format');
  } else if (error.code === 'INSUFFICIENT_BALANCE') {
    console.error('Top up your account');
  }
}

Code	Description	Solution
INVALID_NUMBER	Bad to/from	Use E.164 format
INSUFFICIENT_BALANCE	Out of credit	Top up account
UNREGISTERED_CALLER_ID	from not verified	Register caller ID

📚 Related Resources

• IVR
• Call Recording
• Conferencing
• Voice Overview

---

Need help? Contact Support → | Last Updated: May 2026