ExoML Quickstart
This guide walks through a complete outbound call: Exotel dials a number, your server receives events, and you play a greeting then hang up.
Prerequisites
- An Exotel account with an ExoPhone
- Your API key, API token, and Account SID from my.exotel.com → Developer Settings → API Settings
- A publicly reachable HTTPS server for the event endpoint
Step 1 — Set up your event endpoint
Your server must accept POST requests and return 200 immediately. After acknowledging, issue ExoML actions.
const express = require('express');
const axios = require('axios');
const app = express();
app.use(express.json());
const ACCOUNT_SID = process.env.ACCOUNT_SID;
const API_KEY = process.env.API_KEY;
const API_TOKEN = process.env.API_TOKEN;
const BASE_URL = `https://cpaas-api.in.exotel.com/v2/accounts/${ACCOUNT_SID}`;
app.post('/events', async (req, res) => {
res.sendStatus(200); // Ack immediately
const { event_name, data } = req.body;
if (event_name === 'leg_answered') {
// Play a greeting, then hang up
await axios.post(
`${BASE_URL}/legs/${data.leg_sid}/actions`,
{
exoml: `<?xml version="1.0" encoding="UTF-8"?>
<Flow>
<StartSay language="en" preferredTTSEngine="polly">
Hello! This is a test call from Exotel. Goodbye.
</StartSay>
</Flow>`
},
{ auth: { username: API_KEY, password: API_TOKEN } }
);
}
if (event_name === 'play_completed' || event_name === 'say_completed') {
await axios.post(
`${BASE_URL}/legs/${data.leg_sid}/actions`,
{
exoml: `<?xml version="1.0" encoding="UTF-8"?><Flow><Hangup></Hangup></Flow>`
},
{ auth: { username: API_KEY, password: API_TOKEN } }
);
}
});
app.listen(3000);
Step 2 — Create a leg
curl -u "<api_key>:<api_token>" \
-H "Content-Type: application/json" \
-X POST \
"https://cpaas-api.in.exotel.com/v2/accounts/<account_sid>/legs" \
-d '{
"contact_uri": "+91XXXXXXXXXX",
"exophone": "+91YYYYYYYYYY",
"leg_event_endpoint": "https://your-server.example.com/events"
}'
Response (202 Accepted):
{
"data": {
"leg_sid": "<leg_sid>",
"state": "initiated",
"contact_uri": "+91XXXXXXXXXX",
"exophone": "+91YYYYYYYYYY"
}
}
Step 3 — Handle the call flow
Once you create the leg, Exotel dials the number and posts events to your endpoint in sequence:
leg_connecting— Exotel is diallingleg_ringing— Phone is ringingleg_answered→ your handler plays the greeting (Step 1)play_completed→ your handler sends<Hangup>leg_terminated— Call ended
Step 4 — Verify the leg
After the call, fetch the leg to confirm it completed:
curl -u "<api_key>:<api_token>" \
"https://cpaas-api.in.exotel.com/v2/accounts/<account_sid>/legs/<leg_sid>"
Next steps
- Event endpoint reference — full payload schema and retry behaviour
- Action reference — all ExoML verbs and their attributes
- Legs & Bridges API — create bridges, manage multiple legs