Esta API posibilita la consulta de datos de las interacciones realizadas a través de Zenvia Chat, según los informes ya extraídos actualmente, a partir de la interfaz de Administración.

TOKEN

El token de acceso a la API puede generarse en la interfaz de Administración, a partir del menú:

• Configuraciones
• Integraciones
• API

Enlace: https://zchat-admin.zenvia.com/integrations

CANAL DIGITAL

Equivalente al informe Canales Digitales, permite la consulta de datos consolidados, relacionados con los atendimientos realizados.

Get interactions report:

 GET: https://zchat.zenvia.io/api/ms/external/reports?token=yourApiToken

 Parámetros

• data_type: criterio por el cual se agruparán los datos.

  • period

  • tag

  • department

  • channel

  • agent

• from: Fecha de inicio del período, en el formato AAAA-MM-DD HH:MM:SS 

  • Ej: 2021-04-01T06:00:00

  • Si no se especifica, se buscarán los últimos 30 días.

• to: Fecha final del período, en el formato AAAA-MM-DD HH:MM:SS 

  • Ej: 2021-04-30T18:00:00

  • Si no se especifica, se buscará hasta la fecha actual.

• timezone: Zona horaria deseada, en el formato de 5 dígitos. 

  • Ej: -0300

  • Si no se especifica, se usará el valor predeterminado UTC.

• agents: ID de los agentes, separados por comas, para consultas por agentes específicos.

  • Si no se especifica, se buscarán todos los agentes.

• departments: ID de los departamentos, separados por comas, para consultas por departamentos específicos.

  • Si no se especifica, se buscarán todos los departamentos.

• states: Consulta por interacciones con estados específicos.

  • Ej: 'ENDED', 'UNAVAILABLE', 'CANCELED' o 'DISCARDED'

  • Si no se especifica, se buscarán todos los estados.

• types: Canal a través del cual se realizó la interacción.

  • PHONE - Interacciones por llamadas de voz

  • PHONE_CONF - Conferencias por llamadas de voz

  • WHATSAPP - Interacciones por WhatsApp

  • FACEBOOK - Interacciones por Facebook

  • EMAIL - Interacciones por correo electrónico

  • SMS - Interacciones por SMS

  • TELEGRAM - Interacciones por Telegram

  • TEXT - Interacciones por Web Chat

  • MELI_QST - Interacciones por preguntas en Mercado Libre

  • MELI_MSG - Interacciones postventa en Mercado Libre

• tags: ID de las etiquetas, separadas por comas, para consultas por interacciones con etiquetas específicas.

Obs: Si no se especifica, se buscarán todas las etiquetas.

 Respuesta exitosa: 

 "data": [ { "answered": 3, "backlog": 14, "discarded": 2, "ended": 3, "expired": 0, "made": 0, "missed": 0, "not_answered": 0, "pending": 0, "postponed": 0, "received": 3, "remainder": 12, "sla": 17, "slapr": 0 "title": "2020-02-02", "tma": 13, "tmaxe": 13, "tme": 4, "tmp": 0, "tmpa": 0, "tmpr": 11, "tmr": 2 }, { "answered": 3, "backlog": 14, "discarded": 2, "ended": 3, "expired": 0, "made": 0, "missed": 0, "not_answered": 0, "pending": 0, "postponed": 0, "received": 3, "remainder": 12, "sla": 17, "slapr": 0 "title": "Total", "tma": 13, "tmaxe": 13, "tme": 4, "tmp": 0, "tmpa": 0, "tmpr": 11, "tmr": 2 } ], "status": 200, "success": true }

Respuesta de error: 

{ "error": "Mensaje de error", "status": 401, "success": false }

 

Significado de las Variables:

• title = Título

• backlog = Sobra Anterior (Atendimientos no finalizados el día anterior)

received = Recibidos (Total de atenciones nuevas recibidas en el período)

• made = Efectuadas (Total de atenciones iniciadas por el agente)

• rang = Distribuidas (Atenciones distribuidas automáticamente al agente)

• answered = Realizadas (Atenciones recibidas por un agente y atendidas con intercambio de mensajes)

• ended = Finalizadas (Atenciones atendidas con intercambio de mensajes y marcadas como finalizadas por el agente)

• not_answered = En cola (Atenciones no atendidas y que permanecieron en la cola de espera)

• pending = Pendientes (agente) (Atenciones iniciadas y colocadas en la lista de pendientes (última interacción del cliente))

• postponed = Pendientes (cliente) (Atenciones iniciadas y colocadas en la lista de pendientes (última interacción del agente))

• discarded = Descartadas (Atenciones recibidas por un agente, pero interrumpidas sin intercambio de mensajes)

• missed = Perdidas (Atenciones inactivas que fueron cerradas por el agente)

• expired = Inactivas (Atenciones que expiraron y ya no pueden ser respondidas)

• remainder = Sobrante del día (Atenciones no finalizadas durante el día pero que aún pueden ser atendidas)

• tma = TMA (Tiempo medio de atención en curso (segundos))

• tme = TME (Tiempo medio de espera del cliente en la cola (segundos))

• tmaxe = TmaxE (Tiempo máximo de espera del cliente en la cola (segundos))

• tmpr = TMPR (Tiempo medio de primera respuesta del agente (segundos))

• tmr = TMR (Tiempo medio de respuesta del agente durante la atención (segundos))

• tmpa = TMPA (Tiempo medio para que el agente retome una atención pendiente (segundos))

• tmp = TMP (Tiempo medio para que el cliente retome una atención pendiente (segundos))

• sla = TTM (Tiempo total medio de atención desde el contacto del cliente hasta la finalización por parte del agente (TMA + TME + TMPA) (segundos))

• slapr = SLA de primera respuesta

 

HISTORIAL DE ATENCIONES

Equivalente al informe “Historial de Atenciones”, permite la consulta de todos los datos relacionados con las atenciones realizadas, tanto en el formato estándar como expandido.

Obtener Historial:

• GET: https://zchat.zenvia.io/api/ms/external/history?token=yourApiToken

Obtener Historial Expandido:

• GET: https://zchat.zenvia.io/api/ms/external/history/expanded?token=yourApiToken

 

Parámetros:

• from: Fecha de inicio del período, en el formato AAAA-MM-DD HH:MM:SS 

  • Ej: 2021-04-01T06:00:00

  • Si no se informa, se buscarán los últimos 30 días

• to: Fecha final del período, en el formato AAAA-MM-DD HH:MM:SS 

  • Ej: 2021-04-30T18:00:00

  • Si no se informa, se buscará hasta la fecha actual.

• timezone: Zona horaria deseada, en el formato de 5 dígitos 

  • Ej: -0300

  • Si no se informa, se utilizará la zona horaria UTC por defecto

• active: Define si la búsqueda será por interacciones realizadas o recibidas

  • “true” = Realizadas (interacciones iniciadas por los agentes)

  • “false” = Recibidas (interacciones iniciadas por los usuarios)

  • Si no se informa, se buscarán todas las interacciones

• agents: ID de los agentes, separados por comas, para consultas por agentes específicos

  • Si no se informa, se buscarán todos los agentes

• departments: ID de los departamentos, separados por comas, para consultas por departamentos específicos

  • Si no se informa, se buscarán todos los departamentos

• states: Consulta por interacciones con estados específicos

  • Ej: 'ENDED', 'UNAVAILABLE', 'CANCELED' o 'DISCARDED'

  • Si no se informa, se buscarán todos los estados

• types: Canal por el cual se realizó la interacción

  • PHONE - Interacciones por llamadas de voz

  • PHONE_CONF - Conferencias por llamadas de voz

Aquí está la traducción al español del texto solicitado:

• WHATSAPP - Interacciones por WhatsApp

• FACEBOOK - Interacciones por Facebook

• EMAIL - Interacciones por correo electrónico

• SMS - Interacciones por SMS

• TELEGRAM - Interacciones por Telegram

• TEXT - Interacciones por Web Chat

• MELI_QST - Interacciones por preguntas en Mercado Libre

• MELI_MSG - Interacciones por post-venta de Mercado Libre

• search: Búsqueda por nombre del cliente, correo electrónico del agente o Id de interacción específicos

  • Ejemplo: 

    • search=maria -> realizará una búsqueda por usuarios o correos electrónicos de agentes con el campo ILIKE '%maria%' 

    • search=999 ->  realizará una búsqueda por usuarios o correos electrónicos de agentes con el campo ILIKE '%999%' o interaction_id=999

• limit: número máximo de interacciones por solicitud, con un límite de 10.000 registros

  • Si no se informa, se mostrarán 100 registros por solicitud

• page: Paginación para número de registros superior al límite por solicitud (>=1)

  • Si no se informa, se mostrarán solo los registros dentro del límite de la página 1

Retorno exitoso: 

{ "status": 200, "success": true, "data": [{ "active": "true/false" (quién inició el contacto (enviado/recibido)), "agent": { "id": "id" (agent_id), "name": "name" (nombre del agente), "phone_extension": "phone_extension" (extensión del teléfono del agente) }, "created_at": "created_at_iso" (creado en interacción), "current_state": "status" (último estado de la interacción), "current_state_time": "current_state_time_iso" (hora del último estado de la interacción), "customer": { "id"': "id" (id del cliente), "fields": { (cada campo puede ser una cadena o una matriz (campos únicos/múltiples)) "channel_email": ["phone_1", "phone2"], "channel_external": "", "channel_facebook": "", "channel_mercado_livre": "", "channel_phone": "", "channel_telegram": "", "document": "", "main_identifier": "Ejemplo", "main_photo": "" } }, "department": { "id": "department_id", "name": "nombre del departamento" }, "first_answer_time": "first_answer_time_iso", "id": "protocol", "media": "canal de servicio", "mood": "calificación" (encuesta de satisfacción), "sla_overdue": true }] }

Retorno de error: 

{ "error": "Mensaje de error", "status": 401, "success": false }

 

Significado de las variables:

• expired = Inactivo (Atención que expiró y no puede ser respondida)

• expired_time = Tiempo inactivo (Tiempo que la atención inactiva llevó para ser cerrada por el agente) (en segundos)

• missed = Perdido (Atención inactiva que fue cerrada por el agente)

• canceled = Abandonado por el cliente (Atención interrumpida por el cliente antes de ser iniciada)

• answered = Realizado (Por cuántos agentes se realizó la atención)

• queued = En Fila (Cuántas veces la atención fue a la fila)

• ended = Finalizado (Atención con intercambio de mensajes finalizada por el agente)

• discarded = Descartado por el agente (Atención recibida pero interrumpida por el agente)

• ringing = Distribución (Cuántas veces la atención fue distribuida entre agentes)

• postponed = Pendiente (esperando al cliente) (Cuántas veces la atención fue colocada en la lista de pendientes (última interacción del agente) después de iniciada)

• pending = Pendiente (esperando al agente) (Cuántas veces la atención fue colocada en la lista de pendientes (última interacción del cliente) después de iniciada)

• transferring = Transferido (Cuántas veces la atención fue transferida)

• messages = Total de mensajes (Número de mensajes intercambiados entre agente y cliente)

• queued_time = Tiempo en Fila (Tiempo que la atención estuvo en fila o no fue atendida) (en segundos)

• ringing_time = Tiempo en distribución (Tiempo que la atención estuvo sonando para los agentes) (en segundos)

• missed_time = Tiempo Perdido (Tiempo para que la atención inactiva sea cerrada) (en segundos)

• canceled_time = Tiempo hasta el abandono (Tiempo hasta que el cliente abandona) (en segundos)

• talking_time = Tiempo en atención (Tiempo que la atención estuvo en curso) (en segundos)

• postponed_time = Tiempo esperando al cliente (Tiempo que la atención estuvo esperando mensaje del cliente) (en segundos)

• pending_time = Tiempo esperando al agente (Tiempo que la atención estuvo esperando mensaje del agente) (en segundos)

• first_contact_time = Tiempo para la primera respuesta (Tiempo que el agente tardó en responder al primer mensaje del cliente) (en segundos)

• response_count = Cantidad de respuestas (Cantidad de intercambios de cliente a agente)

• response_time = Tiempo medio de respuesta (Tiempo medio de respuesta del agente en la atención) (en segundos)

• sla_time = Tiempo total de la atención (Tiempo entre el primer mensaje del cliente y la finalización de la atención) (en segundos)

• discarded_time = Tiempo hasta el descarte (Tiempo hasta el descarte del agente) (en segundos)

• browser = Navegador (Navegador del cliente que se puso en contacto)

• ip = Dirección IP (IP del cliente que se puso en contacto)

• os = Sistema operativo (SO del cliente que se puso en contacto)

• source = URL de origen (URL desde la cual el cliente fue redirigido al sitio de atención)

• channel_external = Id Externo

group_name = Nombre del Grupo

• channel_email = Correo electrónico (Correo electrónico del cliente que se puso en contacto)

• channel_phone = Teléfono (Teléfono del cliente que se puso en contacto)

• channel_mercado_livre = Id Mercado Libre

• channel_facebook = Id Facebook

• channel_telegram = Id Telegram

• document = CPF (CPF del cliente que se puso en contacto)

• main_identifier = Nombre (Nombre del cliente que se puso en contacto)

• agent = Agente (Agente que finalizó la atención)

• phone_extension = Extensión (Extensión del agente que finalizó la atención)

• department = Departamento (Departamento responsable de la atención)

• endTime = Última actualización (Fecha y hora de la última actualización del estado de la atención)

• id = Protocolo (Número de protocolo de la atención)

• origin = Origen (Quién inició el contacto)

• startTime = Primer mensaje (Fecha y hora del primer mensaje recibido por el agente en la atención)

• state = Estado (Atención perdida o finalizada)

• type = Canal (Canal de la atención)

• tagCount = Etiquetas (Número de etiquetas usadas en la atención)

• tags = Etiquetas (Etiquetas usadas en la atención)

• mood = Evaluación (Evaluación del cliente en la encuesta de satisfacción de la atención)

• notes = Notas

• sla_overdue = Si el SLA de primera respuesta ha excedido el límite definido en la cuenta, devuelve true, de lo contrario devuelve false

 

HISTORIAL DE CONVERSACIÓN

Para consultar el historial de mensajes de una conversación específica, se puede utilizar el siguiente comando:

 

Get Protocol Messages:

• GET: https://zchat.zenvia.io/api/ms/external/history/{id}/messages?token=yourApiToken

Parámetro:

• id: este parámetro debe ser reemplazado por el número del protocolo que se desea consultar.

Retorno de Éxito: :

{ "data": [ { "origin": "AGENT", "payload": "Your position in queue is 1", "timestamp": "2021-02-12T19:37:50", "type": "text", "url": null }, { "origin": "CLIENT", "payload": "Something", "timestamp": "2021-02-12T19:28:36", "type": "image", "url": "https://omz-files-socialmedias.s3.amazonaws.com/test" } ], "status": 200, "success": true }

 

Retorno de Error: 

{ "error": "Mensaje de error", "status": 401, "success": false }

 

ATENCIONES EN CURSO

Permite la consulta de datos de las atenciones en curso. Equivalente a los informes “Monitoreo”, “Fila de Espera”, “Pendientes” e “Inactivos”.

Get ongoing interactions:

•  GET: https://zchat.zenvia.io/api/ms/external/ongoing?token=yourApiToken

 

Parámetros:

• agents: ID de los agentes, separados por comas, para consultas por agentes específicos.

Si no se especifica, se buscarán todos los agentes.

• departments: Id de los departamentos, separados por comas, para consultas por departamentos específicos.

Si no se especifica, se buscarán todos los departamentos.

• states: Consulta por interacciones con estados específicos. Ej: ‘NOT_ANSWER’, 'QUEUED', 'TALKING', 'RINGING', 'MISSED', 'PENDING', 'POSTPONED'

Si no se especifica, se buscarán todos los estados.

• types: Canal por el cual se realizó la interacción:
  • PHONE - Interacciones por llamadas de voz
  • PHONE_CONF - Conferencias por llamadas de voz
  • WHATSAPP - Interacciones por WhatsApp
  • FACEBOOK - Interacciones por Facebook
  • EMAIL - Interacciones por correo electrónico
  • SMS - Interacciones por SMS
  • TELEGRAM - Interacciones por Telegram
  • TEXT - Interacciones por chat web
  • MELI_QST - Interacciones por preguntas en Mercado Libre
  • MELI_MSG - Interacciones por postventa de Mercado Libre

• limit: número máximo de interacciones por solicitud, con un límite de 10.000 registros.

Si no se especifica, se mostrarán 100 registros por solicitud.

• page: Paginación para número de registros superiores al límite por solicitud (>=1).

Si no se especifica, se mostrarán solo los registros dentro del límite de la página 1.

 

Retorno de Éxito:

{ "status": 200, "success": true, "data": [{ "active": "true/false" (quién inició el contacto (enviado/recibido)), "agent": { "id": "id" (agent_id), "name": "name" (agent_name), "phone_extension": "phone_extension" (agent_phone_extension) "status": "ONLINE/OFFLINE" }, "created_at": "created_at_iso" (fecha de creación de la interacción), "current_state": "status" (último estado de la interacción), "current_state_time": "current_state_time_iso" (última hora del estado de la interacción), "customer": { "id"': "id" (customer id), "fields": { (cada campo puede ser una cadena o un array (campos únicos/múltiples)) "channel_email": ["phone_1", "phone2"], "channel_external": "", "channel_facebook": "", "channel_mercado_livre": "", "channel_phone": "", "channel_telegram": "", "document": "", "main_identifier": "Example", "main_photo": "" } }, "department": { "id": "