Allo

Rechercher des éléments de conversation

Cet endpoint est paginé. Utilisez page et size dans le corps de la requête pour contrôler les résultats. Voir Pagination.

POST/v2/api/conversations/items/search

Cet endpoint est paginé. Utilisez page et size dans le corps de la requête pour contrôler les résultats. Voir Pagination.

Appels sortants tombés sur une messagerie

Quand un appel sortant est décroché par le répondeur du contact, result reste ANSWERED, car l'opérateur considère qu'un répondeur qui décroche est une réponse. Deux champs portent l'information à la place :

ChampSignification
detected_outbound_voicemailUn répondeur a décroché (détection automatique ou transcription)
voicemail_leftUn message a effectivement été laissé après le bip

Les deux sont indépendants : detected_outbound_voicemail: true avec voicemail_left: false signifie que l'appel est tombé sur une messagerie et que l'appelant a raccroché sans laisser de message. L'un ou l'autre peut valoir null quand le signal n'a jamais été déterminé. null n'est pas équivalent à false.

Comportement de la recherche

Le champ search est une recherche par mots-clés, pas une requête en langage naturel. Extrayez les mots-clés de la question de l'utilisateur avant de les transmettre.

L'utilisateur demandeValeur de search
"Trouver les appels où les clients se sont plaints de la facturation""billing complaint"
"Qu'avons-nous discuté à propos de la politique de remboursement ?""refund policy"
"Montrer les conversations mentionnant la tarification entreprise""enterprise pricing"

Fonctionnement de la correspondance :

  • Les termes sont combinés avec AND : "billing refund" correspond aux éléments contenant les deux mots
  • La correspondance par préfixe est utilisée : "bill" correspond à "billing", "billed", etc.
  • La recherche porte sur : les transcriptions d'appels, les résumés d'appels et le contenu des messages SMS
  • Utilisez sort=RELEVANCE pour classer les résultats par qualité de correspondance plutôt que par date

Filtrer par type

typeRenvoie
ALL (par défaut)Les appels et les messages
CALLUniquement les appels
SMSLes messages, fax inclus
FAXUniquement les fax

Un fax est renvoyé comme un élément de type SMS avec message_type FAX. Voir Fax.

Notes sur les champs

ChampNull quand
summaryÉléments SMS, ou appels dont le résumé IA n'est pas encore disponible
durationÉléments SMS (s'applique uniquement aux appels)
resultÉléments SMS (s'applique uniquement aux appels)
detected_outbound_voicemailAppels entrants, éléments SMS, ou appels sortants sans détection
voicemail_leftAppels entrants, éléments SMS, ou appels sortants pour lesquels ce n'est pas déterminé
recording_urlEnregistrement désactivé, appel sans réponse, éléments SMS, ou comptes vendus sous la marque d'un partenaire en marque blanche
recording_download_urlComptes qui n'ont pas été créés par un partenaire, appels d'une équipe HIPAA, appels sans enregistrement, utilisateur de la clé qui ne peut pas écouter l'enregistrement, ou éléments SMS
recording_download_expires_atMêmes cas que recording_download_url
recording_durationEnregistrement désactivé, appel sans réponse, ou éléments SMS
transcriptNon demandé via extend=transcript, ou éléments SMS
contentÉléments d'appel (s'applique uniquement aux SMS)
statusÉléments d'appel (s'applique uniquement aux SMS)
attachmentsÉléments d'appel. Un SMS sans photo ni fichier renvoie un tableau vide.
page_countAppels, messages qui ne sont pas des fax, ou fax dont le nombre de pages n'est pas encore connu
tagsÉléments SMS (les tags s'appliquent uniquement aux appels)

duration est la durée totale de l'appel en secondes, sonnerie incluse. recording_duration est la durée de conversation, celle affichée dans l'application Allo pour les appels enregistrés. Pour les appels sans enregistrement, l'application utilise duration.

recording_download_url télécharge le fichier de l'enregistrement sans connexion à Allo, pendant 48 heures. Il n'est renvoyé que sur les lignes des comptes créés par un partenaire, jamais pour un appel HIPAA. Voir Liens vers l'enregistrement.

attachments liste les photos et autres fichiers d'un MMS, chacun avec un download_url valable 30 minutes. Voir Fichiers joints aux MMS.

Paramètre extend

ValeurEffet
transcriptInclure les transcriptions complètes des appels sur chaque élément

Passer une valeur non prise en charge renvoie une erreur 400 avec le code UNSUPPORTED_EXTEND_VALUE.

Autorisation

Authorizationstring · headerrequis

Api-Key ak_live_…

Corps

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 champs
fromstring<date>requis

Start date

tostring<date>requis

End date

Réponses

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

OPENWONLOST

userobject
3 champs
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 champs
contactobject
6 champs
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 champs
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 champs
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 champs
pageinteger
sizeinteger
total_countinteger
total_pagesinteger
has_moreboolean
400
401
429