Allo

Modifier la configuration

Modifie toute partie de la configuration du réceptionniste, sauf le prompt et l'activation. Renvoie la configuration complète après l'écriture, dans la même…

PATCH/v2/api/numbers/{number}/agent

Comportement

Modifie toute partie de la configuration du réceptionniste, sauf le prompt et l'activation. Renvoie la configuration complète après l'écriture, dans la même forme que Lire la configuration.

Deux règles de fusion s'appliquent :

  • Les valeurs simples sont fusionnées. name, les informations sur l'activité, language, voice_id, greeting_message, closing_message, tone_of_voice, answer_type et knowledge.text gardent leur valeur actuelle si vous les omettez.
  • Les collections sont remplacées. capabilities, business_hours, transfer_rules et scheduling.calendars sont des ensembles complets. Envoyez-en un et il remplace ce qui était configuré, omettez-le et il reste intact.

Pour ajouter une seule règle de transfert, lisez d'abord les règles existantes et renvoyez-les avec la nouvelle. Pour garder une capacité activée, incluez-la dans chaque map capabilities que vous envoyez.

Un champ que cet endpoint ne déclare pas est refusé avec 400 UNKNOWN_FIELD, y compris les champs en lecture seule comme custom_prompt, prompt_metadata et status. Rien n'est ignoré en silence.

Règles de transfert

description est le champ qui décide si un transfert fonctionne. Le réceptionniste compare ce que dit l'appelant à ce texte : écrivez-le comme le motif de l'appelant (« questions de facturation », « veut réserver une intervention »), pas comme une instruction adressée au réceptionniste.

Chaque règle a besoin de la cible qu'implique son type :

TypeChamp requisDestination
EXTERNAL_NUMBERtarget_numberN'importe quel numéro, au format E.164
MEMBERtarget_member_idUn membre de l'équipe, par son id issu de GET /v2/api/users
INBOXtarget_line_numberUne autre de vos lignes Allo

Visez une cible autre que la ligne que vous configurez. Une règle qui renvoie l'appelant vers la même ligne le rend au réceptionniste qui vient de le transférer, et l'appel boucle. L'API accepte une telle règle : c'est à vous de l'éviter.

Les règles sont recréées à chaque écriture : une erreur désigne l'entrée fautive par son index, par exemple transfer_rules[1].description.

Horaires d'ouverture

schedule est obligatoire dès que vous envoyez business_hours. Les heures sont exprimées en secondes depuis minuit : 9h à 17h s'écrit 32400 à 61200, et un jour absent de la liste est fermé.

Agendas de réservation

scheduling.calendars est une map dont les clés sont des id d'agenda issus de Lister les agendas. Un agenda que le réceptionniste n'a pas encore lui est rattaché, un agenda associé à [] reste rattaché sans type d'événement sélectionné, et un agenda absent de la map perd l'accès.

Les types d'événement viennent de Lire un agenda. Renvoyez id, slug, title et length_in_minutes tels quels, et ajoutez votre propre description pour indiquer quand le réceptionniste doit réserver celui-là plutôt qu'un autre.

Connecter un agenda à l'espace de travail est un flux OAuth, réalisé dans l'app Allo. Cet endpoint choisit parmi les connexions qui existent déjà.

Texte de connaissances

knowledge.text est déprécié. Ajoutez plutôt des sites web avec Ajouter un site web.

Il fonctionne toujours. Allo l'enregistre comme une source texte nommée « Business knowledge » dans la bibliothèque de connaissances de l'équipe, utilisée par cette ligne. Un texte différent modifie cette même source, et une chaîne vide la désactive pour cette ligne.

Limites des champs

ChampLimite
name, business_name, business_email, business_website, business_industry64 caractères
business_address255 caractères
greeting_message, closing_message1000 caractères
transfer_rules[].description255 caractères
transfer_rules[].transfer_message1000 caractères
knowledge.text (déprécié)25000 caractères

Erreurs

  • 400 UNKNOWN_FIELD : un champ que cet endpoint n'accepte pas, nommé dans param.
  • 400 INVALID_REQUEST_BODY : un champ déclaré n'a pas passé la validation. Le champ fautif est dans errors[].
  • 400 MISSING_FIELD : une partie obligatoire d'une collection manque, nommée dans param.
  • 400 INVALID_AGENT_LANGUAGE / 400 INVALID_AGENT_CAPABILITY : une valeur inconnue. Les valeurs acceptées sont listées dans le message.
  • 400 INVALID_TIMEZONE : business_hours.timezone n'est pas un identifiant IANA.
  • 400 INVALID_PHONE_NUMBER : business_phone n'est pas un numéro exploitable.
  • 400 AGENT_TRANSFER_RULE_TARGET_REQUIRED : une règle n'a pas la cible qu'exige son type.
  • 403 AGENT_TRANSFER_RULE_MEMBER_NO_LINE_ACCESS : le membre visé n'a pas accès à cette ligne.
  • 404 AGENT_VOICE_NOT_FOUND : aucune voix ne porte ce voice_id. Listez-les avec Lister les voix.
  • 404 AGENT_CALENDAR_NOT_FOUND : un id d'agenda de la map n'est pas visible pour vous.
  • 404 PHONE_NUMBER_NOT_FOUND : ce numéro n'est pas un numéro auquel vous avez accès.

Autorisation

Authorizationstring · headerrequis

Api-Key ak_live_…

Paramètres de chemin

numberstringrequis

Allo phone number in E.164 format

Corps

namestring
business_namestring
business_addressstring
business_phonestring

E.164 format.

business_emailstring
business_websitestring
business_industrystring
languageenum<string>

frfr-CAen-USen-GBesdehr

voice_idstring

An id from GET /v2/api/voices, listed under the receptionist's language.

greeting_messagestring
closing_messagestring
tone_of_voiceenum<string>

FRIENDLYPROFESSIONALNEUTRALENTHUSIASTIC

answer_typeenum<string>

CONCISESTANDARDDETAILED

capabilitiesobject

The complete set of toggles. A capability left out of the map is turned off, so read the current ones first and send them all back.

business_hoursobject

Replaces the whole week. schedule is required when this key is sent.

2 champs
timezonestring

IANA timezone identifier.

scheduleobject[]requis
2 champs
dayenum<string>requis

MOTUWETHFRSASU

scheduleobject[]requis

The open periods of that day. An empty array closes the day.

2 champs
start_timeintegerrequis
end_timeintegerrequis
transfer_rulesobject[]

Replaces the whole rule set. Send [] to remove every rule.

6 champs
descriptionstring

The caller's reason, in the caller's words. This is what the receptionist matches what it hears against, so phrase it as a reason ('billing or invoice questions'), not as an instruction.

typeenum<string>

EXTERNAL_NUMBER transfers to any phone number, MEMBER to a teammate, INBOX to another Allo line.

EXTERNAL_NUMBERMEMBERINBOX

transfer_messagestring | null

What the receptionist says before transferring.

target_numberstring | null

Required for EXTERNAL_NUMBER. E.164 format.

target_member_idstring | null

Required for MEMBER. A user id from GET /v2/api/users.

target_line_numberstring | null

Required for INBOX. Another of your Allo numbers, in E.164 format.

schedulingobject
1 champs
calendarsobject

The complete set of calendars the receptionist may book on, keyed by an id from GET /v2/api/calendars. A calendar it does not have yet is linked to it, one mapped to [] stays linked with no event type selected, and one left out loses access.

knowledgeobject

Only the free-text knowledge is writable here. Websites and files have their own endpoints.

1 champs
textstring

Deprecated: add websites instead. Stored as the line's "Business knowledge" text source in the team's knowledge library; a different text edits that source in place, an empty string turns it off for this line.

Réponses

200The configuration after the write
dataobject

The whole configuration of one line's AI receptionist.

7 champs
agentobject

The AI receptionist's own settings. Everything here except id, status, is_default, created_at and updated_at is writable with PATCH /v2/api/numbers/{number}/agent.

18 champs
idstring | null
statusenum<string>

ACTIVE: the receptionist answers incoming calls. FORWARDING: it does not, and calls go to your business phone. Read-only here, change it with PUT /v2/api/numbers/{number}/agent/status.

ACTIVEFORWARDING

namestring | null

The name the receptionist gives itself on a call.

is_defaultboolean

True while the line still runs Allo's default receptionist, with no prompt, greeting, closing or knowledge of its own.

business_namestring | null
business_addressstring | null
business_phonestring | null

The business's own phone number, in E.164 format.

business_emailstring | null
business_websitestring | null
business_industrystring | null
languageenum<string>

The language the receptionist speaks. Pick a voice_id listed under the same language.

frfr-CAen-USen-GBesdehr

voice_idstring | null

Identifier of a voice from GET /v2/api/voices.

greeting_messagestring | null

What the receptionist says when it picks up.

closing_messagestring | null

What the receptionist says before hanging up.

tone_of_voiceenum<string>

FRIENDLYPROFESSIONALNEUTRALENTHUSIASTIC

answer_typeenum<string>

How long the receptionist's answers run.

CONCISESTANDARDDETAILED

created_atstring<date-time> | null
updated_atstring<date-time> | null
promptobject

The receptionist's prompt. Exactly one of the two keys is present: sections for a prompt written in the section format, custom_prompt for an older line whose prompt was written as freeform text. custom_prompt is the render of the sections, so it is never reported alongside them.

2 champs
sectionsobject[]
4 champs
sectionenum<string>

objectivepersonalitybehaviorsprohibitedrequired_fieldsobjective_completion

titlestring

Human-readable title, derived server-side from section.

contentstring | null
fieldsobject[]
custom_promptstring | null
capabilitiesobject

What the receptionist is allowed to do on a call. All three are always reported.

3 champs
SCHEDULINGboolean

Book appointments on the calendars in scheduling.calendars.

CALL_TRANSFERboolean

Transfer the call using the rules in transfer_rules.

WARM_TRANSFERboolean

Announce the caller to the person taking the transfer before connecting them.

business_hoursobject

When the business is open. A day left out of schedule is closed.

2 champs
timezonestring | null

IANA timezone identifier.

scheduleobject[]
2 champs
dayenum<string>requis

MOTUWETHFRSASU

scheduleobject[]requis

The open periods of that day. An empty array closes the day.

transfer_rulesobject[]
6 champs
descriptionstring

The caller's reason, in the caller's words. This is what the receptionist matches what it hears against, so phrase it as a reason ('billing or invoice questions'), not as an instruction.

typeenum<string>

EXTERNAL_NUMBER transfers to any phone number, MEMBER to a teammate, INBOX to another Allo line.

EXTERNAL_NUMBERMEMBERINBOX

transfer_messagestring | null

What the receptionist says before transferring.

target_numberstring | null

Required for EXTERNAL_NUMBER. E.164 format.

target_member_idstring | null

Required for MEMBER. A user id from GET /v2/api/users.

target_line_numberstring | null

Required for INBOX. Another of your Allo numbers, in E.164 format.

schedulingobject
1 champs
calendarsobject[]

The calendars this receptionist may book on. Empty when it has none, which is not the same as the workspace having none: list those with GET /v2/api/calendars.

7 champs
calendar_connection_idstring
namestring | null
providerenum<string>

GOOGLE_CALENDARCAL_COMCALENDLYOUTLOOK

statusenum<string>

ACTIVEDISCONNECTED

is_team_defaultboolean
ownerobject

The teammate who connected the calendar.

event_typesobject[]
knowledgeobject

What the receptionist knows about the business: facts, prices, policies, hours.

3 champs
textstring | null

Deprecated. Free-text knowledge, up to 25000 characters, stored as the line's "Business knowledge" text source.

websitesobject[]
5 champs
idstring
urlstring
statusenum<string>

ACTIVE when this line's receptionist answers from the website, DISABLED when this line does not use it.

ACTIVEDISABLED

created_atstring<date-time> | null
updated_atstring<date-time> | null
filesobject[]
5 champs
idstring
file_namestring
statusenum<string>

ACTIVEDISABLED

created_atstring<date-time> | null
updated_atstring<date-time> | null
400
401
403
404
429