Lancer des appels depuis votre propre logiciel

• Une clé API créée par la personne qui a créé le compte de la clinique. AlloMia refuse les appels lancés avec une clé créée par quelqu’un d’autre. Consultez Clés pour connecter d’autres logiciels.
• Un agent IA configuré pour ce type d’appel. Ses instructions disent quoi faire pendant l’appel. Les conseils de Campagnes d’appels de rappel et de suivi s’appliquent aussi ici.
• Un des numéros de téléphone de votre clinique pour appeler. Le patient le voit comme numéro de l’appelant. Un numéro acheté dans AlloMia est prêt. Un numéro de votre propre fournisseur a besoin d’un trunk sortant : consultez Connecter le système téléphonique de votre clinique. Une adresse SIP créée avec Créer SIP ne peut pas servir.
• Chaque appel qui obtient une réponse compte dans les minutes de votre clinique, comme tout autre appel. Un appel resté sans réponse ne compte pas.

• assistantId, l’agent IA : dans le menu de gauche, cliquez sur Agents IA (Voice Agents si votre tableau de bord s’affiche en anglais). Dans la liste Mes agents, placez votre souris sur l’agent, cliquez sur les trois points (⋮), puis sur Copier l’ID.
• phoneNumberId, le numéro à partir duquel appeler : cliquez sur Numéros de téléphone. Au bout de la ligne du numéro, cliquez sur les trois points (⋮), puis sur Copier ID.

Envoyez POST https://allomia.com/api/outbound avec l’en-tête Authorization: Bearer suivi de votre clé, et l’en-tête Content-Type: application/json. Le corps JSON contient ces champs :

• phoneNumber (obligatoire) : le numéro à appeler, au format E.164, par exemple +15145551234. Un numéro de 10 chiffres sans + est traité comme un numéro canadien ou américain.
• assistantId (obligatoire) : l’agent IA qui fait l’appel.
• phoneNumberId (obligatoire) : le numéro de la clinique à partir duquel appeler.
• customerName (facultatif) : le nom du patient, jusqu’à 40 caractères. Il est conservé avec la demande d’appel, mais l’agent IA ne le voit pas.
• dynamicVariables (facultatif) : des détails pour cet appel, sous forme de noms avec des valeurs texte, par exemple first_name et appointment_date. Dans les instructions de l’agent IA, écrivez un nom entre doubles accolades, comme {{first_name}}, et AlloMia le remplace par la valeur. Les détails fonctionnent dans les instructions, pas dans le message d’accueil. Pour que l’agent puisse utiliser le nom du patient, envoyez-le aussi ici.
• callbackUrl (facultatif) : une adresse HTTPS où AlloMia envoie le résultat à la fin de l’appel.

Quand la requête est acceptée, la réponse est le code HTTP 200 avec outboundCallId, contactId, status et message. Gardez outboundCallId : vous en avez besoin pour vérifier l’appel.

• status vaut calling : AlloMia est en train de faire l’appel.
• status vaut failed, avec le message « Outbound call failed to dispatch » : l’appel n’a pas pu être fait, même si le code HTTP est 200. Aucun avis de fin d’appel ne suivra. Vérifiez le numéro à partir duquel vous appelez, puis réessayez.

Vérifier le statut. Envoyez GET https://allomia.com/api/outbound/OUTBOUND_CALL_ID/status, en remplaçant OUTBOUND_CALL_ID par votre outboundCallId. Le status vaut pending ou calling pendant l’appel, puis l’une de ces valeurs finales :

• completed : on a répondu à l’appel, une personne ou une boîte vocale. AlloMia ne peut pas faire la différence.
• no-answer ou busy : personne n’a répondu, ou la ligne était occupée. AlloMia ne rappelle pas.
• failed : l’appel n’a pas pu être fait, ou s’est terminé par une erreur.

Une fois le statut final, callDetails donne startedAt, endedAt, duration en secondes et endedReason, par exemple customer-ended-call. Avant, sa valeur est null.

Ou attendre l’avis de fin d’appel (callback). Si vous avez envoyé un callbackUrl, AlloMia envoie un seul POST avec un corps JSON quand l’appel atteint un statut final. Le corps contient event (toujours call.completed), outboundCallId, contactId, status, timestamp, callDetails et dynamicVariables (les détails que vous avez envoyés).

• Répondez avec n’importe quel code 2xx en moins de 10 secondes. Sinon, AlloMia réessaie après 1, 5 et 30 secondes, soit 4 essais en tout, puis s’arrête.
• AlloMia l’envoie au plus une fois par appel. Il n’est pas envoyé quand la première réponse indiquait déjà failed.
• Utilisez une adresse HTTPS difficile à deviner. Avant d’agir sur un avis de fin d’appel, vérifiez que l’outboundCallId correspond à un appel que vous avez lancé et confirmez le résultat avec la requête de statut.

L’appel s’affiche aussi dans Journal d’appels avec le type Sortant, comme tout autre appel.

Avec une clé de votre clinique, votre logiciel peut aussi afficher la liste des appels de votre clinique et lire un appel, avec son résumé et les liens vers sa transcription et son enregistrement. Consultez List Calls et Get Call sur le site pour développeurs (en anglais).

Les erreurs sont renvoyées en JSON, avec le message dans un champ error.

• 401 « Unauthorized » : la clé est absente, erronée ou supprimée.
• 403 « Insufficient permissions » : la clé n’a pas été créée par la personne qui a créé le compte de la clinique.
• 400 « Invalid request data » : la liste details nomme chaque champ qui pose problème, par exemple un assistantId manquant ou un nom de plus de 40 caractères.
• 404 « Phone number not found » ou « Assistant not found » : l’identifiant est erroné ou appartient à une autre clinique. Copiez-le de nouveau.
• 422 « Organization is inactive or not found » : le compte de la clinique n’est pas actif. Écrivez au soutien technique d’AlloMia.
• 500 avec « Phone number format is invalid » : corrigez phoneNumber. 500 avec « This number cannot be used as an outbound caller ID » : pour phoneNumberId, choisissez un numéro de téléphone, pas une adresse SIP. Ces deux erreurs viennent de la requête, même si le code est 500 pour l’instant.
• La requête de statut reçoit 401 « Organization ID not found in authorization » : la requête de statut accepte seulement une clé de clinique, créée dans Paramètres (Organization Settings). Utilisez-en une, ou fiez-vous à l’avis de fin d’appel.
• Autres erreurs 500 : réessayez un peu plus tard. Si le problème continue, écrivez à support@allomia.com en donnant l’heure de la requête et l’outboundCallId, si vous l’avez.

Pour la liste complète des champs et des exemples, consultez Create Outbound Call sur le site pour développeurs (en anglais).