Session Link

API per sviluppatori

Ottieni dai tuoi sistemi un link diretto alla conversazione di un cliente; il cliente e la conversazione vengono creati se non esistono ancora.

• WhatsApp
• Instagram
• REST API

Installa da MonoStoreScopri su monochat.ai

Panoramica

Una sola chiamata API con un canale e il numero di telefono o l’email di un cliente restituisce un link che apre la conversazione di quel cliente in MonoChat. Se il cliente o la conversazione non esistono ancora, vengono creati.

Inserisci il link nel tuo CRM, help desk o schermata degli ordini e il tuo team passa direttamente da lì alla chat.

Punti di forza

• Apri o crea. Funziona per un cliente su un determinato canale WhatsApp, Instagram o altro, tramite numero di telefono o email.
• Instrada lungo il percorso. Assegna la conversazione a un operatore, tramite id o email, o a un gruppo di lavoro nella stessa chiamata.
• Stesso cliente, stessa conversazione. Richiamandola di nuovo per lo stesso cliente e canale restituisce la conversazione esistente.

Installazione e configurazione

1. Installa Session Link da Impostazioni › MonoStore › App, oppure apri il link di installazione app.monochat.ai/apps/vvKJe8Nbp4EQNy2KA. Se non hai un account MonoChat, il link ti permette di registrarti prima e installa l’app per te.
2. Crea un token API in Profilo › Token API. Il token viene mostrato una sola volta, quindi copialo subito. Vedi Token API.
3. Apri Impostazioni › Session Link API. La documentazione che trovi lì mostra l’indirizzo esatto dell’endpoint del tuo workspace e richieste di esempio pronte da copiare. Prova l’esempio con uno dei tuoi canali.
4. Aggiungi al tuo CRM, help desk o schermata degli ordini un pulsante "Chatta su WhatsApp" che chiama l’API e apre l’url restituito.

nota

• Il link apre MonoChat per le persone che hanno effettuato l’accesso e sono autorizzate a vedere quella conversazione.
• La chiamata apre soltanto la conversazione; non invia alcun messaggio al cliente. Usa WhatsApp Template API per scrivere per primo.

Funzionalità

Link alla conversazione

La risposta fornisce il link che apre la conversazione in MonoChat e l’id della conversazione.

Cliente creato se necessario

Viene creato un nuovo cliente con il nome e il cognome che invii; la risposta ti dice se il cliente era già noto.

Assegnazione

Assegna a un operatore tramite id o email, o a un gruppo di lavoro.

Schermata della documentazione

Il riferimento API con l’indirizzo esatto dell’endpoint del tuo workspace e richieste di esempio pronte da copiare.

Riferimento API

La chiamata è una POST con un corpo JSON, autenticata con un token API.

POST https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

• <slug> è il tenant slug del tuo workspace, la parte dopo /tenants/ nel tuo indirizzo MonoChat.
• <app-folder> è la cartella in cui è stata installata l’app. La schermata Impostazioni › Session Link API mostra l’indirizzo completo con entrambi i valori già inseriti.
• Crea il token in Profilo › Token API. Vedi Token API.

Campi della richiesta

Campo	Obbligatorio	Descrizione
connectorBrand	sì	Il tipo di canale, ad esempio whatsapp o instagram.
channelUsername	sì	Il nome utente del tuo canale in MonoChat, ad esempio il tuo numero WhatsApp senza +.
customer.identityType	sì	phoneNumber o email.
customer.identity	sì	Il numero di telefono del cliente (prefisso internazionale, senza +) o il suo indirizzo email.
customer.firstname, customer.lastname	no	Usati quando il cliente è nuovo per MonoChat. Predefinito -.
assignment.type	no	agent (id utente dell’operatore), agentIdentity (email dell’operatore) o workgroup (id del gruppo di lavoro).
assignment.value	con assignment.type	L’id o l’email a cui assegnare la conversazione.

Esempio di richiesta

curl --location 'https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
  "connectorBrand": "whatsapp",
  "channelUsername": "905334445566",
  "customer": {
    "identityType": "phoneNumber",
    "identity": "905306667788",
    "firstname": "Ayşe",
    "lastname": "Yılmaz"
  },
  "assignment": { "type": "agentIdentity", "value": "sarah@yourcompany.com" }
}'

Risposta

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "Zeii7vpeeFFnsJepZ",
    "isOldUser": true
  }
}

Campo	Descrizione
url	Apre la conversazione in MonoChat.
sessionId	L’id della conversazione. Lo stesso cliente sullo stesso canale ottiene sempre la stessa conversazione.
isOldUser	false quando il cliente è stato creato da questa chiamata.

Errori

Una chiamata non riuscita risponde con uno stato di errore e un messaggio:

Messaggio	Causa
connectorBrand, channelUsername and customer fields are required	Manca un campo obbligatorio di primo livello.
customer.identityType must be one of: phoneNumber, email	identityType è mancante o ha un altro valore.
customer.identity field is required	Mancano il numero di telefono o l’email del cliente.
Channel not found	Nel tuo workspace non c’è alcun canale di quel tipo con quel nome utente.
Customer Channel not found	Non è stato possibile associare il cliente a un’identità di canale.
Agent user not found	Nessun operatore con l’email indicata in assignment.value.
401	L’header Authorization manca o il token non è valido.

Schermate

Un CRM, un help desk e una schermata di gestione ordini, ciascuno apre la conversazione giusta in MonoChatAssegnazione della conversazione a un operatore o a un gruppo di lavoro nella stessa chiamata APIUn nuovo cliente e una nuova conversazione creati automaticamente dalla richiesta APIUna sola chiamata API restituisce il link alla conversazioneUn pulsante “Chatta su WhatsApp” in un CRM apre la conversazione del cliente con un clicRichiamando di nuovo l’API per lo stesso cliente si apre la conversazione esistente

FAQ

Session Link invia un messaggio al cliente?

No. Apre o crea soltanto la conversazione e ne restituisce il link. Per scrivere per primo al cliente, usa l’app WhatsApp Template API.

Con quali canali funziona?

WhatsApp, Instagram e gli altri canali collegati al tuo workspace MonoChat. Nella richiesta indichi il tipo di canale e il nome utente del tuo canale.

Creerà conversazioni duplicate?

No. Lo stesso cliente sullo stesso canale ottiene sempre la stessa conversazione.

Chi può aprire il link?

Le persone che hanno effettuato l’accesso a MonoChat e sono autorizzate a vedere quella conversazione.

Correlati

• WhatsApp Template API
• App MonoStore
• Impostazioni del profilo
• Gruppi di lavoro