Session Link

API para desarrolladores

Obtenga un enlace directo a la conversación de un cliente desde sus propios sistemas; el cliente y la conversación se crean si aún no existen.

• WhatsApp
• Instagram
• API REST

Instalar desde MonoStoreVerlo en monochat.ai

Descripción general

Una llamada de API con un canal y el teléfono o correo electrónico de un cliente devuelve un enlace que abre la conversación de ese cliente en MonoChat. Si el cliente o la conversación aún no existen, se crean.

Ponga el enlace en su CRM, help desk o pantalla de pedidos y su equipo salta desde ahí directamente al chat.

Aspectos destacados

• Abrir o crear. Funciona para un cliente en un canal determinado de WhatsApp, Instagram u otro, por teléfono o correo electrónico.
• Enrute sobre la marcha. Asigne la conversación a un agente, por id o correo electrónico, o a un grupo de trabajo en la misma llamada.
• Mismo cliente, misma conversación. Volver a llamar para el mismo cliente y canal devuelve la conversación existente.

Instalación y configuración

1. Instale Session Link desde Configuración › MonoStore › Aplicaciones, o abra el enlace de instalación app.monochat.ai/apps/vvKJe8Nbp4EQNy2KA. Si no tiene una cuenta de MonoChat, el enlace le permite registrarse primero e instala la app por usted.
2. Cree un token de API en Perfil › Tokens de API. El token se muestra una sola vez, así que cópielo de inmediato. Consulte Tokens de API.
3. Abra Configuración › Session Link API. La documentación que hay allí muestra la dirección exacta del endpoint de su espacio de trabajo y solicitudes de ejemplo listas para copiar. Pruebe el ejemplo con uno de sus canales.
4. Añada un botón "Chat on WhatsApp" a su CRM, help desk o pantalla de pedidos que llame a la API y abra la url devuelta.

nota

• El enlace abre MonoChat para las personas que han iniciado sesión y tienen permiso para ver esa conversación.
• La llamada solo abre la conversación; no envía ningún mensaje al cliente. Use WhatsApp Template API para escribir primero.

Funciones

Enlace a la conversación

La respuesta incluye el enlace que abre la conversación en MonoChat y el id de la conversación.

Cliente creado si hace falta

Se crea un cliente nuevo con el nombre y los apellidos que envíe; la respuesta indica si el cliente ya era conocido.

Asignación

Asigne a un agente por id o correo electrónico, o a un grupo de trabajo.

Pantalla de documentación

La referencia de la API con la dirección exacta de endpoint de su espacio de trabajo y solicitudes de ejemplo listas para copiar.

Referencia de la API

La llamada es un POST con un cuerpo JSON, autenticada con un token de 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> es el tenant slug de su espacio de trabajo, la parte posterior a /tenants/ en su dirección de MonoChat.
• <app-folder> es la carpeta en la que se instaló la app. La pantalla Configuración › Session Link API muestra la dirección completa con ambos valores ya rellenados.
• Cree el token en Perfil › Tokens de API. Consulte Tokens de API.

Campos de la solicitud

Campo	Obligatorio	Descripción
connectorBrand	sí	El tipo de canal, por ejemplo whatsapp o instagram.
channelUsername	sí	El nombre de usuario de su canal en MonoChat, por ejemplo su número de WhatsApp sin +.
customer.identityType	sí	phoneNumber o email.
customer.identity	sí	El teléfono del cliente (con prefijo de país, sin +) o su dirección de correo electrónico.
customer.firstname, customer.lastname	no	Se usan cuando el cliente es nuevo en MonoChat. Por defecto -.
assignment.type	no	agent (id de usuario del agente), agentIdentity (correo electrónico del agente) o workgroup (id del grupo de trabajo).
assignment.value	con assignment.type	El id o correo electrónico al que asignar la conversación.

Ejemplo de solicitud

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

Respuesta

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

Campo	Descripción
url	Abre la conversación en MonoChat.
sessionId	El id de la conversación. El mismo cliente en el mismo canal siempre obtiene la misma conversación.
isOldUser	false cuando el cliente fue creado por esta llamada.

Errores

Una llamada fallida responde con un estado de error y un mensaje:

Mensaje	Causa
connectorBrand, channelUsername and customer fields are required	Falta un campo obligatorio de nivel superior.
customer.identityType must be one of: phoneNumber, email	Falta identityType o tiene otro valor.
customer.identity field is required	Falta el teléfono o el correo electrónico del cliente.
Channel not found	No hay ningún canal de ese tipo con ese nombre de usuario en su espacio de trabajo.
Customer Channel not found	No se pudo asociar al cliente con una identidad de canal.
Agent user not found	No hay ningún agente con el correo electrónico indicado en assignment.value.
401	Falta la cabecera Authorization o el token no es válido.

Capturas de pantalla

Un CRM, un help desk y una pantalla de gestión de pedidos, cada uno abriendo la conversación correcta en MonoChatAsignación de la conversación a un agente o a un grupo de trabajo en la misma llamada de APIUn cliente y una conversación nuevos creados automáticamente desde la solicitud de APIUna llamada de API devuelve el enlace a la conversaciónUn botón “Chat on WhatsApp” en un CRM abre la conversación del cliente con un clicVolver a llamar a la API para el mismo cliente abre la conversación existente

Preguntas frecuentes

¿Session Link envía un mensaje al cliente?

No. Solo abre o crea la conversación y devuelve un enlace a ella. Para escribir primero al cliente, use la app WhatsApp Template API.

¿Con qué canales funciona?

WhatsApp, Instagram y los demás canales conectados a su espacio de trabajo de MonoChat. En la solicitud indica el tipo de canal y el nombre de usuario de su canal.

¿Creará conversaciones duplicadas?

No. El mismo cliente en el mismo canal siempre obtiene la misma conversación.

¿Quién puede abrir el enlace?

Las personas que han iniciado sesión en MonoChat y tienen permiso para ver esa conversación.

Relacionado

• WhatsApp Template API
• Apps de MonoStore
• Ajustes del perfil
• Grupos de trabajo