API Outbound
Lancer des appels sortants par HTTP, depuis n8n, Make, Zapier ou ton serveur. Point de terminaison, authentification, requête, réponse, idempotence et limites.
Avec l'API Outbound, tu lances un appel de ton agent avec une seule requête HTTP. Tu transmets le numéro de destination, le numéro appelant et les données de contexte, bhomy envoie l'agent, et celui-ci mène la conversation avec les valeurs de ton contexte.
En bref
| Point | Valeur |
|---|---|
| Point de terminaison | POST https://app.bhomy.ai/api/v1/outbound |
| Authentification | Authorization: Bearer bhomy_live_sk_… |
| Format | JSON, Content-Type: application/json |
| Réponse en cas de succès | 202 Accepted |
| Limite | 60 requêtes en 60 secondes, par clé et par adresse IP |
| Condition | identité confirmée, numéro appelant avec un agent |
Créer une clé API
- Dans le tableau de bord, ouvre Clé API et clique sur Nouvelle clé.
- Saisis un nom, par exemple « Make.com rappel de rendez-vous ».
- Copie la clé et conserve-la en lieu sûr. Elle n'est affichée qu'une seule fois.
La requête
| Champ | Obligatoire | Contenu |
|---|---|---|
toNumber | oui | numéro de destination au format E.164 avec le signe plus, par exemple +491701234567 |
fromNumber | oui | ton numéro appelant, importé ou connecté via SIP, avec un agent attribué |
context | non | objet avec des valeurs pour la salutation et le prompt |
L'agent est déterminé par le numéro appelant. Tu n'indiques pas d'ID d'agent.
curl -X POST https://app.bhomy.ai/api/v1/outbound \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 4f9c2b1e-7a3d-4c55-9a0e-2d6f8b1c3e77" \
-d '{
"toNumber": "+491701234567",
"fromNumber": "+494012345678",
"context": {
"customer_name": "Anna Berger",
"appointment": "15 janvier"
}
}'
Les espaces, tirets et parenthèses dans les numéros sont autorisés, tout comme un (0) après l'indicatif du pays. L'API refuse un numéro sans signe plus au lieu de deviner un pays.
Utiliser le contexte dans la conversation
Chaque champ de context est disponible comme variable. Dans le prompt ou la salutation, tu l'écris entre doubles accolades :
Bonjour {{customer_name}}, ici l'assistant de la société Sommer. Je vous appelle au
sujet de votre rendez-vous du {{appointment}}.
Si un champ manque dans context, bhomy le retire du texte. Garde des valeurs plates, formulées comme on les dit.
La réponse
En cas de succès, l'API répond avec 202. L'agent compose ensuite le numéro. Le résultat de la conversation apparaît plus tard dans l'historique des appels et est envoyé à tes automatisations.
{
"success": true,
"callId": "call_8f2a1c",
"roomName": "outbound_call_8f2a1c",
"status": "queued",
"dispatchId": "AD_x7Kp2",
"message": "Calling +491701234567"
}
En cas d'erreur, error contient un code fixe auquel ton intégration peut réagir, et message une explication. Tous les codes avec leur solution : Codes d'erreur de l'API.
Idempotence : chaque appel une seule fois
Les outils d'automatisation répètent les requêtes quand une réponse n'arrive pas. Pour que personne ne soit appelé deux fois, tu envoies un header Idempotency-Key avec une nouvelle valeur par appel, par exemple un UUID ou l'ID de la ligne dans ton tableau.
| Situation | Réponse |
|---|---|
| Même clé, même requête | la réponse de la première requête, avec le header Idempotent-Replayed: true. Le numéro n'est pas recomposé |
| Même clé, autre requête | 422 avec idempotency_key_reused |
| La première requête est encore en cours | 409 avec idempotency_request_in_progress et Retry-After |
| Clé invalide : vide, plus de 255 caractères ou pas en ASCII | 400 avec invalid_idempotency_key |
Sans ce header, chaque requête lance un nouvel appel.
Limites
| Limite | Réponse quand elle est atteinte |
|---|---|
| 60 requêtes en 60 secondes, par clé et par adresse IP | 429 avec rate_limit_exceeded et Retry-After |
| appels simultanés de ton forfait | 429 avec concurrent_limit_reached et Retry-After |
| Destinations d'un numéro importé : numéros fixes et mobiles allemands | 422 avec imported_number_destination |
En cas de 429, attends le nombre de secondes indiqué dans Retry-After avant de réessayer.
Exemples pour les outils d'automatisation
| Outil | Module | Guide |
|---|---|---|
| n8n | HTTP Request | n8n |
| Make | HTTP › Make a request | Make |
| Zapier | Webhooks by Zapier › Custom Request | Zapier |
Récupérer les résultats
L'API indique seulement si la demande a été acceptée. Le déroulement de la conversation, tu le reçois après l'appel via le Ticket CRM dans l'onglet Outils › Automation : avec callId, résumé, transcription et données collectées. Grâce au callId, tu associes le résultat à ta demande.
Cette page vous a-t-elle aidé ?