Allo

Search conversation items

Search and filter items across all conversations. Supports keyword search across transcripts, summaries, and message content.

POST/v2/api/conversations/items/search

This endpoint is paginated. Use page and size in the request body to control results. See Pagination.

Outbound calls that reached a voicemail

When an outbound call is answered by the contact's answering machine, result stays ANSWERED, because the carrier treats a machine pickup as an answer. Two fields carry the voicemail signal instead:

FieldMeaning
detected_outbound_voicemailA machine picked up (answering machine detection, or the transcript)
voicemail_leftA message was actually left after the beep

Both are independent: detected_outbound_voicemail: true with voicemail_left: false means the call reached a voicemail and the caller hung up without leaving a message. Either can be null when that particular signal was never determined. null is not the same as false.

Search behavior

The search field is a keyword search, not a natural language query. Extract keywords from the user's question before passing them.

User askssearch value
"Find calls where customers complained about billing""billing complaint"
"What did we discuss about the refund policy?""refund policy"
"Show me conversations mentioning enterprise pricing""enterprise pricing"

How matching works:

  • Terms are AND'd: "billing refund" matches items containing both words
  • Prefix matching is used: "bill" matches "billing", "billed", etc.
  • Searches across: call transcripts, call summaries, and SMS message content
  • Use sort=RELEVANCE to rank results by match quality instead of date

Filter by type

typeReturns
ALL (default)Calls and messages
CALLCalls only
SMSMessages, faxes included
FAXFaxes only

A fax is returned as an item of type SMS with message_type FAX. See Faxes.

Field notes

FieldNull when
summarySMS items, or calls where AI summary is not yet available
durationSMS items (only applies to calls)
resultSMS items (only applies to calls)
detected_outbound_voicemailInbound calls, SMS items, or outbound calls where no detection ran
voicemail_leftInbound calls, SMS items, or outbound calls where it was not determined
recording_urlRecording disabled, call not answered, SMS items, or accounts sold under a white-label partner's brand
recording_download_urlAccounts not created by a partner, calls on a HIPAA-enabled team, calls without a recording, a key user who cannot play the recording, or SMS items
recording_download_expires_atSame as recording_download_url
recording_durationRecording disabled, call not answered, or SMS items
transcriptNot requested via extend=transcript, or SMS items
contentCall items (only applies to SMS)
statusCall items (only applies to SMS)
attachmentsCall items. An SMS with no photo or file returns an empty array.
page_countCalls, messages that are not faxes, or a fax whose page count is not known yet
tagsSMS items (tags only apply to calls)

duration is the total call length in seconds, ringing included. 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 duration.

recording_download_url downloads the recording file with no Allo login, for 48 hours. It is returned only on lines of accounts created by a partner, never for a HIPAA call. See Recording links.

attachments lists the photos and other files of an MMS, each with a download_url valid for 30 minutes. See MMS attachments.

Extend parameter

ValueEffect
transcriptInclude full call transcripts on each item

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

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Body

allo_numberstring
contact_numberstring
user_idstring
directionenum<string>

INBOUNDOUTBOUND

typeenum<string>

SMS returns all messages, faxes included. FAX returns only faxes.

CALLSMSFAXALL

resultenum<string>

ANSWEREDVOICEMAILTRANSFERRED

tagsstring[]
unreadboolean
unrespondedboolean
searchstring

Keyword search (not natural language). Extract keywords from the user's question. Terms are AND'd with prefix matching — 'billing refund' matches items containing both words, 'bill' matches 'billing'. Searches across call transcripts, summaries, and SMS content.

sortenum<string>

DATE_DESCDATE_ASCRELEVANCE

extendstring
pageinteger
sizeinteger
dateobject
2 fields
fromstring<date>required

Start date

tostring<date>required

End date

Responses

200Search results
dataobject[]
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
2 fields
idstring
namestring
dealsobject[]
3 fields
idstring
namestring
statusenum<string>

OPENWONLOST

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
6 fields
namestring
companystring
job_titlestring
websitestring
addressstring
emailsstring[]
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.

paginationobject
5 fields
pageinteger
sizeinteger
total_countinteger
total_pagesinteger
has_moreboolean
400
401
429