Allo

Lister les conversations

Cet endpoint est paginé. Utilisez les paramètres de requête page et size pour contrôler les résultats. Voir Pagination.

GET/v2/api/conversations

Cet endpoint est paginé. Utilisez les paramètres de requête page et size pour contrôler les résultats. Voir Pagination.

Ligne ou boîte de réception

Envoyez exactement un des deux paramètres allo_number ou inbox_id. Envoyer les deux, ou aucun, retourne une erreur 400 avec le code INVALID_REQUEST.

  • allo_number liste les conversations d'une ligne Allo. Une ligne à laquelle l'appelant n'a pas accès retourne une erreur 403 avec le code ALLO_NUMBER_FORBIDDEN.
  • inbox_id liste les conversations d'une de vos boîtes de réception, avec des conversations de plusieurs lignes (chaque ligne de résultat a un seul allo_number). Les sources et filtres enregistrés de la boîte s'appliquent, mais pas les onglets À traiter et Les miennes de l'app. "Non lues uniquement" n'est pas enregistré sur une boîte : passez le paramètre de requête unread. Une boîte qui n'est pas la vôtre retourne une erreur 404 avec le code INBOX_NOT_FOUND.

Chaque conversation a un champ allo_number, la ligne Allo sur laquelle elle se trouve. Utilisez-le pour épingler ou répondre quand vous listez par boîte.

Erreurs liées aux boîtes et aux épingles

StatutCodeQuand
400INVALID_REQUESTallo_number et inbox_id sont envoyés tous les deux, ou aucun
400INVALID_PARAMETERUn paramètre de requête est mal formé, par exemple pinned=yes. param le nomme
400FEATURE_NOT_SUPPORTEDLister par inbox_id ou avec pinned n'est pas encore disponible. param indique lequel
400CONTACT_FILTER_NOT_SUPPORTEDLa boîte a des filtres de contacts enregistrés et l'espace de travail utilise encore l'ancien modèle de contacts. Retirez contact_ids et contact_list_ids des filtres de la boîte
403ALLO_NUMBER_FORBIDDENL'appelant n'a pas accès à la ligne allo_number
404INBOX_NOT_FOUNDAucune boîte avec cet ID pour l'appelant. Juste après une création, l'erreur peut être passagère : si retryable vaut true, réessayez une fois
422CONTACT_FILTER_TOO_LARGELes filtres de contacts de la boîte correspondent à trop de numéros, ou contiennent plus de 50 IDs de contacts ou 10 IDs de listes. Le type de l'erreur est validation_error

Conversations épinglées

Chaque conversation a un champ pinned. Passez pinned=true pour lister seulement les conversations épinglées, ou pinned=false pour les exclure. Épinglez et désépinglez avec Épingler une conversation et Désépingler une conversation.

Notes sur les champs

ChampNull quand
last_item.summaryÉléments SMS, ou appels dont le résumé IA n'est pas encore disponible
last_item.durationÉléments SMS (s'applique uniquement aux appels)
last_item.resultÉléments SMS (s'applique uniquement aux appels)
last_item.recording_urlEnregistrement désactivé, appel sans réponse, ou éléments SMS
last_item.recording_durationEnregistrement désactivé, appel sans réponse, ou éléments SMS
last_item.transcriptNon demandé via extend=transcript, ou éléments SMS
last_item.contentÉléments d'appel (s'applique uniquement aux SMS)
last_item.statusÉléments d'appel (s'applique uniquement aux SMS)
last_item.attachmentsÉléments d'appel. Un SMS sans photo ni fichier renvoie un tableau vide. Voir Fichiers joints aux MMS.
last_item.page_countAppels, messages qui ne sont pas des fax, ou fax dont le nombre de pages n'est pas encore connu
last_item.contactsTableau vide lorsqu'aucun contact correspondant n'existe dans le carnet d'adresses

last_item.duration est la durée totale de l'appel en secondes, sonnerie incluse. last_item.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 last_item.duration.

Paramètre extend

Le paramètre de requête extend accepte une liste de champs optionnels séparés par des virgules. Actuellement pris en charge :

ValeurEffet
transcriptInclure les transcriptions complètes des appels sur les éléments de conversation

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

Autorisation

Authorizationstring · headerrequis

Api-Key ak_live_…

Paramètres de requête

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

Réponses

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

OPENWONLOST

last_activitystring<date-time>
last_itemobject
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
dealsobject[]
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
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.

pinnedbooleanrequis

Whether the caller pinned this conversation.

allo_numberstring | null

Allo line of the conversation (E.164).

paginationobject
5 champs
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 champs
typestring
codestring
messagestring
retryableboolean
request_idstring
retry_after_secondsinteger | null
429