API Outbound

Name: bhomy
Price: 89 EUR
Availability: InStock
Author: bhomy

Avviare chiamate in uscita via HTTP, da n8n, Make, Zapier o dal tuo server. Endpoint, autenticazione, richiesta, risposta, idempotenza e limiti.

Disponibile in: ProIndividualUltima verifica il 25 ottobre 2026

Con l'API Outbound avvii una chiamata del tuo agente con una sola richiesta HTTP. Passi numero di destinazione, numero mittente e dati di contesto, bhomy fa partire l'agente e questo conduce la conversazione con i valori del tuo contesto.

In sintesi

Voce	Valore
Endpoint	`POST https://app.bhomy.ai/api/v1/outbound`
Autenticazione	`Authorization: Bearer bhomy_live_sk_…`
Formato	JSON, `Content-Type: application/json`
Risposta in caso di successo	`202 Accepted`
Limite	60 richieste in 60 secondi, per chiave e per indirizzo IP
Requisito	identità confermata, numero mittente con agente

Creare una chiave API

Nella dashboard apri Chiave API e clicca su Nuova chiave.
Inserisci un nome, per esempio «Make.com promemoria appuntamenti».
Copia la chiave e conservala al sicuro. Viene mostrata solo questa volta.

La richiesta

Campo	Obbligatorio	Contenuto
`toNumber`	sì	numero di destinazione in formato E.164 con il segno più, per esempio `+491701234567`
`fromNumber`	sì	il tuo numero mittente, importato o collegato via SIP, con un agente assegnato
`context`	no	oggetto con i valori per saluto e prompt

L'agente è determinato dal numero mittente. Non indichi alcun ID agente.

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 gennaio"
    }
  }'

Spazi, trattini e parentesi nei numeri sono ammessi, così come uno (0) dopo il prefisso internazionale. L'API rifiuta un numero senza segno più invece di indovinare un paese.

Usare il contesto nella conversazione

Ogni campo di context è disponibile come variabile. Nel prompt o nel saluto lo scrivi tra doppie parentesi graffe:

Buongiorno {{customer_name}}, sono l'assistente dell'azienda Sommer. La chiamo per il
suo appuntamento del {{appointment}}.

Se un campo manca in context, bhomy lo rimuove dal testo. Mantieni i valori piatti e come si pronunciano.

La risposta

In caso di successo l'API risponde con 202. Poi l'agente compone il numero. L'esito della conversazione compare in seguito nello storico chiamate e viene inviato alle tue automazioni.

{
  "success": true,
  "callId": "call_8f2a1c",
  "roomName": "outbound_call_8f2a1c",
  "status": "queued",
  "dispatchId": "AD_x7Kp2",
  "message": "Calling +491701234567"
}

In caso di errore, error contiene un codice fisso a cui la tua integrazione può reagire, e message una spiegazione. Tutti i codici con la soluzione: Codici di errore dell'API.

Idempotenza: ogni chiamata esattamente una volta

Gli strumenti di automazione ripetono le richieste quando una risposta non arriva. Perché nessuno venga chiamato due volte, invii un header Idempotency-Key con un valore nuovo per ogni chiamata, per esempio un UUID o l'ID della riga nel tuo foglio di calcolo.

Situazione	Risposta
Stessa chiave, stessa richiesta	la risposta alla prima richiesta, con l'header `Idempotent-Replayed: true`. Il numero non viene ricomposto
Stessa chiave, richiesta diversa	`422` con `idempotency_key_reused`
La prima richiesta è ancora in corso	`409` con `idempotency_request_in_progress` e `Retry-After`
Chiave non valida: vuota, più lunga di 255 caratteri o non ASCII	`400` con `invalid_idempotency_key`

Senza l'header, ogni richiesta avvia una nuova chiamata.

Limiti

Limite	Risposta al raggiungimento
60 richieste in 60 secondi, per chiave e per indirizzo IP	`429` con `rate_limit_exceeded` e `Retry-After`
chiamate contemporanee del tuo piano	`429` con `concurrent_limit_reached` e `Retry-After`
Destinazioni di un numero importato: numeri fissi e mobili tedeschi	`422` con `imported_number_destination`

Con 429 attendi i secondi indicati in Retry-After prima di riprovare.

Esempi per gli strumenti di automazione

Strumento	Modulo	Guida
n8n	HTTP Request	n8n
Make	HTTP › Make a request	Make
Zapier	Webhooks by Zapier › Custom Request	Zapier

Ricevere i risultati

L'API segnala solo se l'incarico è stato accettato. Come è andata la conversazione lo ricevi dopo la chiamata tramite il Ticket CRM nella scheda Strumenti › Automazione: con callId, riepilogo, trascrizione e dati raccolti. Con il callId associ l'esito al tuo incarico.

Questa pagina ti è stata utile?