Collega WhatsApp a Bitrix24 CRM su un numero Coexistence

Come parla n8n con Bitrix24?

Tramite un webhook in entrata, che in Bitrix24 non è un ricevitore ma una credenziale. Lo crei nelle risorse per sviluppatori di Bitrix24, scegli gli ambiti (scope) che può usare e ottieni un URL con l'indirizzo del tuo portale, l'id dell'utente che lo ha creato e un codice segreto. Aggiungendo il nome di un metodo a quell'URL chiami la REST API come quell'utente, con i suoi permessi.

In n8n ogni passaggio verso Bitrix24 è quindi un nodo HTTP che invia una POST a quell'URL più un metodo come crm.lead.add.json. Non c'è nessun flusso OAuth da completare e nessuna app da pubblicare. Dai al webhook solo lo scope CRM e crealo da un utente i cui permessi coprano i lead e i contatti che il workflow deve vedere, perché Bitrix24 controlla l'accesso come quell'utente.

Quali metodi di Bitrix24 chiama il workflow?

Tre, in ordine, dopo che il nodo Webhook di n8n riceve il messaggio da Meta.

crm.duplicate.findbycomm con type PHONE e il numero del mittente restituisce gli id di eventuali lead, contatti e aziende che lo possiedono. È la ricerca giusta perché cerca in tutti e tre insieme ed è pensata per confrontare i recapiti, non un campo di testo.

Se non restituisce nulla, crm.lead.add crea un lead con il nome del profilo WhatsApp come titolo e il numero nel campo telefono. Poi crm.timeline.comment.add scrive il testo del messaggio come commento sul record, con ENTITY_TYPE, ENTITY_ID e COMMENT. Il commento compare nella timeline del record accanto a chiamate ed email, dove un venditore guarda già.`

POST https://yourcompany.bitrix24.com/rest/1/<secret>/crm.duplicate.findbycomm.json
{ "type": "PHONE", "values": ["14155550188"] }

POST .../crm.lead.add.json
{ "fields": { "TITLE": "WhatsApp: Maria", "PHONE": [{ "VALUE": "14155550188", "VALUE_TYPE": "MOBILE" }] } }

POST .../crm.timeline.comment.add.json
{ "fields": { "ENTITY_TYPE": "lead", "ENTITY_ID": 4211, "COMMENT": "do you have anything friday?" } }

Come influisce il limite di frequenza sul workflow?

Bitrix24 misura le chiamate REST con un leaky bucket. Ogni richiesta aumenta un contatore, il contatore si svuota a ritmo fisso ogni secondo e, superata una soglia, la richiesta successiva riceve un 503 con QUERY_LIMIT_EXCEEDED. Sui piani Enterprise il contatore si svuota di 5 al secondo con soglia 250; su tutti gli altri piani di 2 con soglia 50.

Ogni messaggio in arrivo costa due o tre chiamate, quindi un flusso costante non si avvicina mai al limite. Un picco sì: cinquanta clienti che rispondono allo stesso template nel giro di un minuto sono fino a 150 chiamate. Imposta i nodi HTTP perché riprovino in caso di fallimento con una breve attesa ed esegui le esecuzioni del workflow una alla volta, così il picco si scarica su Bitrix24 invece di rimbalzare.

Le risposte scritte dal telefono arrivano su Bitrix24?

Possono arrivare. Su un numero Coexistence l'app WhatsApp Business continua a funzionare e, quando qualcuno risponde da lì, Meta invia un echo del messaggio in uscita alla stessa destinazione del webhook, nel campo smb_message_echoes.

Un secondo ramo del workflow gestisce questi echo come i messaggi in arrivo, con il commento contrassegnato come in uscita. Il record mostra così la conversazione completa, con le frasi del cliente e le risposte del negozio in ordine.

Le risposte che il workflow invia da sé tramite la Cloud API sono già nelle sue mani quando partono, quindi registrale in quel momento invece di aspettare che torni un webhook.

Errori comuni

• Incollare l'URL del webhook in entrata in codice lato client o in un documento condiviso. Il segreto al suo interno concede tutti gli scope assegnati al webhook.
• Creare il webhook da un utente che non vede tutti i lead. Le ricerche mancano dei record e il workflow crea duplicati.
• Inviare un picco di chiamate senza nuovi tentativi. Bitrix24 risponde 503 QUERY_LIMIT_EXCEEDED e quei messaggi non arrivano mai nella timeline.

Domande frequenti

Continua a leggere