Getting started
Syncing data
Searching conversations
Find calls where customers mentioned billing issues
Keyword search across all call transcripts and summaries:
POST /v2/api/conversations/items/search
{
"search": "billing issues",
"type": "CALL",
"sort": "RELEVANCE"
}
Search terms are AND'd and use prefix matching — "bill" matches "billing", "billed", etc.
Search what we discussed about refunds with a contact
POST /v2/api/conversations/items/search
{
"contact_number": "+14155551234",
"search": "refunds",
"sort": "RELEVANCE"
}
Show all interactions with a contact
POST /v2/api/conversations/items/search
{
"contact_number": "+14155551234"
}
Returns the full timeline of calls and SMS with a contact, including matched contacts, company, and deals.
Get full context on a specific call
GET /v2/api/conversations/items/cll-abc123?extend=transcript
Returns the call with summary, tags, recording URL, and full transcript. transcript is the only supported extend value.
How many calls were missed last week?
Use the search endpoint with size=1 to get just the count:
POST /v2/api/conversations/items/search
{
"date": { "from": "2026-04-14", "to": "2026-04-21" },
"result": "VOICEMAIL",
"type": "CALL",
"size": 1
}
Read pagination.total_count from the response — no need to fetch all results.
This counts inbound calls that went to voicemail. Outbound calls that reached the contact's answering machine keep result: "ANSWERED" — identify those with the detected_outbound_voicemail field on each item.
Taking actions
Tag a call and then find all calls with that tag
# 1. Tag the call
POST /v2/api/conversations/items/cll-abc123/tags
{ "tags": ["qualified"] }
# 2. Find all calls with that tag
POST /v2/api/conversations/items/search
{ "tags": ["qualified"] }
Adding a tag that already exists returns 409 TAG_ALREADY_EXISTS — no duplicate is created.
Mark a conversation as read
PUT /v2/api/conversations/%2B14155551234/action
{ "action": "READ" }
To scope to a specific Allo number:
PUT /v2/api/conversations/%2B14155551234/action
{ "action": "READ", "allo_number": "+14155550100" }
All actions are idempotent — calling READ on an already-read conversation is a no-op.
Archive a conversation
PUT /v2/api/conversations/%2B14155551234/action
{ "action": "ARCHIVE" }
This archives the contact and marks all items as read.
Send an SMS follow-up
SMS sending uses the v1 API endpoint:
POST /v1/api/sms
{
"to": "+14155551234",
"allo_number": "+14155550100",
"content": "Thanks for your call! Let me know if you have any other questions."
}
Requires the SMS_SEND scope. See Send SMS for details.
Analytics and reporting
What is my cold calling performance this week compared to last?
# 1. Get the outbound funnel with week-over-week comparison
POST /v2/api/analytics/outbound
{
"date": { "from": "2026-04-14", "to": "2026-04-21" },
"compare_date": { "from": "2026-04-07", "to": "2026-04-14" },
"tags": ["meeting_booked"],
"granularity": "DAY"
}
The response includes the full funnel (dials, connected, conversations, conversions) with change vs last week, daily time series, heatmap, and leaderboard.
# 2. Drill into the calls that converted (use extend=items)
POST /v2/api/analytics/outbound
{
"date": { "from": "2026-04-14", "to": "2026-04-21" },
"tags": ["meeting_booked"],
"granularity": "DAY",
"extend": "items",
"stage": "CONVERSION"
}
# 3. Get full details (summary, transcript, tags)
POST /v2/api/conversations/items/batch
{ "ids": ["cll-abc123", "cll-def456"] }
Get team performance for last month
POST /v2/api/analytics/overview
{
"date": { "from": "2026-03-01", "to": "2026-03-31" },
"compare_date": { "from": "2026-02-01", "to": "2026-02-28" }
}
Returns total calls, talk time, answer rate, and per-user breakdown — all with change vs the comparison period.
Compare two reps' performance
POST /v2/api/analytics/overview
{
"date": { "from": "2026-04-01", "to": "2026-04-21" },
"compare_date": { "from": "2026-03-01", "to": "2026-03-31" },
"user_ids": ["usr-abc123", "usr-def456"]
}
The breakdown in the response includes both users with their individual metrics and change vs the comparison period.
Team and setup
Resolve a team member name to filter conversations
# 1. Find the user
GET /v2/api/users
# 2. Use their ID to filter
POST /v2/api/conversations/items/search
{ "user_id": "usr-abc123", "type": "CALL" }