Allo

List conversations

Returns a paginated list of conversations grouped by contact phone number, sorted by most recent activity. Listing by inbox id or with pinned can return 400…

GET/v2/api/conversations

This endpoint is paginated. Use page and size query parameters to control results. See Pagination.

Line or inbox

Send exactly one of allo_number or inbox_id. Sending both, or neither, returns 400 with code INVALID_REQUEST.

  • allo_number lists the conversations of one Allo line. A line the caller cannot access returns 403 with code ALLO_NUMBER_FORBIDDEN.
  • inbox_id lists the conversations of one of your inboxes, with conversations from several lines (each row has one allo_number). The inbox's saved sources and filters apply, but not the app's Needs action and Mine tabs. "Unread only" is not saved on an inbox: pass the unread query parameter. An inbox that is not yours returns 404 with code INBOX_NOT_FOUND.

Each conversation has an allo_number field, the Allo line it is on. Use it to pin or reply when listing by inbox.

Inbox and pinned errors

StatusCodeWhen
400INVALID_REQUESTBoth allo_number and inbox_id are sent, or neither
400INVALID_PARAMETERA query parameter is malformed, for example pinned=yes. param names it
400FEATURE_NOT_SUPPORTEDListing by inbox_id or with pinned is not available yet. param names which one
400CONTACT_FILTER_NOT_SUPPORTEDThe inbox has saved contact filters and the workspace is still on the old contact model. Remove contact_ids and contact_list_ids from the inbox filters
403ALLO_NUMBER_FORBIDDENThe caller cannot access the allo_number line
404INBOX_NOT_FOUNDNo inbox with this ID for the caller. Right after a create it can be transient: when retryable is true, retry once
422CONTACT_FILTER_TOO_LARGEThe inbox's contact filters resolve to too many numbers, or hold more than 50 contact IDs or 10 contact list IDs. The error type is validation_error

Pinned conversations

Each conversation has a pinned field. Pass pinned=true to list only pinned conversations, or pinned=false to leave them out. Pin and unpin with Pin conversation and Unpin conversation.

Field notes

FieldNull when
last_item.summarySMS items, or calls where AI summary is not yet available
last_item.durationSMS items (only applies to calls)
last_item.resultSMS items (only applies to calls)
last_item.recording_urlRecording disabled, call not answered, or SMS items
last_item.recording_durationRecording disabled, call not answered, or SMS items
last_item.transcriptNot requested via extend=transcript, or SMS items
last_item.contentCall items (only applies to SMS)
last_item.statusCall items (only applies to SMS)
last_item.attachmentsCall items. An SMS with no photo or file returns an empty array. See MMS attachments.
last_item.page_countCalls, messages that are not faxes, or a fax whose page count is not known yet
last_item.contactsEmpty array when no matching contact exists in the address book

last_item.duration is the total call length in seconds, ringing included. last_item.recording_duration is the talk time, which is what the Allo app displays for recorded calls. For calls without a recording, the app falls back to last_item.duration.

Extend parameter

The extend query parameter accepts a comma-separated list of optional fields to include. Currently supported:

ValueEffect
transcriptInclude full call transcripts on conversation items

Passing an unsupported value returns a 400 error with code UNSUPPORTED_EXTEND_VALUE.

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Query parameters

allo_numberstring

Filter by Allo number (E.164). Send exactly one of allo_number or inbox_id. List your numbers with GET /v2/api/numbers to find the right one.

inbox_idstring

List the conversations of one of your inboxes (inb-*), from all of its lines (each row has its own allo_number). The inbox's sources and saved filters apply, but not the app's Needs action and Mine tabs; pass unread yourself. Send exactly one of allo_number or inbox_id.

last_activity_sincestring<date-time>

Only return conversations with activity after this timestamp (ISO 8601). Ideal for incremental sync.

unreadboolean
pinnedboolean

Only pinned (true) or only unpinned (false) conversations. Any other value returns 400 INVALID_PARAMETER.

pageinteger

Page number (1-indexed)

sizeinteger

Results per page

extendstring

Comma-separated optional fields. Supported: transcript

Responses

200List of conversations
dataobject[]
6 fields
contact_numberstring
contactsobject[]
4 fields
idstring
namestring
companyobject | null
2 fields
idstring
namestring
dealsobject[]
3 fields
idstring
namestring
statusenum<string>

OPENWONLOST

last_activitystring<date-time>
last_itemobject
26 fields
idstring
typeenum<string>

CALL for a call, SMS for a message. Faxes are SMS items with message_type set to FAX.

CALLSMS

directionenum<string>

INBOUNDOUTBOUND

allo_numberstring
contact_numberstring
contactsobject[]
4 fields
idstring
namestring
companyobject | null
dealsobject[]
userobject
3 fields
idstring
namestring
emailstring
datestring<date-time>
durationinteger | null

Total call length in seconds, from when the call starts (ringing included) to when it ends. For the talk time shown in the Allo app, use recording_duration.

resultenum<string>

Call outcome. Null for SMS items. An outbound call that reached voicemail reports VOICEMAIL. FAILED_EXTERNAL only appears on older calls. New values may be added: handle unknown values gracefully.

ANSWEREDVOICEMAILTRANSFERRED_AITRANSFERRED_EXTERNALBLOCKEDFAILEDFAILED_EXTERNALRECEIVEDCLOSED

detected_outbound_voicemailboolean | null

Outbound calls only. true when the call was answered by an answering machine, false when a human answered, null when no detection ran for this call (never set on inbound calls or SMS). Note that result stays ANSWERED for these calls — the carrier considers a machine pickup an answer.

voicemail_leftboolean | null

Outbound calls only. true when a message was actually left on the voicemail, false when the caller hung up without leaving one, null when not determined. Independent of detected_outbound_voicemail: either can be set without the other.

recording_urlstring | null

Link to the call recording. Absent when the call was not recorded, and for accounts sold under a white-label partner's brand: use recording_download_url there.

recording_download_urlstring | null

Signed link that downloads the recording with no login, valid for 48 hours. Returned only for lines of accounts created by a partner, never for a call on a HIPAA-enabled team, and only when the key's user can play the recording. For a fresh link, call GET /v2/api/conversations/items/{id}/recording.

recording_download_expires_atstring<date-time> | null

When recording_download_url stops working.

recording_durationinteger | null

Length of the call recording in seconds: the talk time, excluding ringing. This is the duration shown in the Allo app for recorded calls. null when the call was not recorded.

summarystring | null
tagsstring[]
extracted_dataobject | null

Contact details Allo's AI picked up from the call transcript, under a contact object: name, company, job_title, website, address (strings, empty when not mentioned) and emails (array). Null for SMS items and for calls Allo has not analyzed.

1 fields
contactobject
data_collectedobject | null

Legacy field kept for compatibility. An empty object on current calls. Null for SMS items.

transcriptobject[]
3 fields
sourceenum<string>

USEREXTERNAL

timestring<date-time>
textstring
contentstring | null
statusenum<string>

PENDINGSENTDELIVEREDFAILED

message_typeenum<string>

SMSMMSWHATSAPPFAX

attachmentsobject[]

Photos and other files sent with the message, in the order they were sent. For a fax, the faxed PDF. An empty array for a message with no files, and null for a call.

5 fields
file_namestring
content_typestring

MIME type of the file.

file_sizeinteger<int64> | null

Size of the file in bytes.

download_urlstring | null

Signed link that downloads the file with no login, valid for 30 minutes. null for a message on a HIPAA-enabled team. For a fresh link, fetch the item again.

download_expires_atstring<date-time> | null

When download_url stops working.

page_countinteger | null

Number of pages of a fax. null for calls, for messages that are not faxes, and for a fax whose page count is not known yet.

pinnedbooleanrequired

Whether the caller pinned this conversation.

allo_numberstring | null

Allo line of the conversation (E.164).

paginationobject
5 fields
pageinteger
sizeinteger
total_countinteger
total_pagesinteger
has_moreboolean
400
401
403
404
422The inbox's contact filters resolve to too many numbers or hold more than 50 IDs (CONTACT_FILTER_TOO_LARGE, type validation_error)
errorobject
6 fields
typestring
codestring
messagestring
retryableboolean
request_idstring
retry_after_secondsinteger | null
429