Introducción al envío de interacciones

El sistema de envío de interacciones de Iris proporciona un modelo homogéneo de llamadas, independiente del canal desde el que se generen. Esto permite centralizar y estandarizar el tratamiento de las comunicaciones, sin importar si se originan desde WhatsApp, SMS, email u otro canal.

Antes de ver esta sección por favor, revisa las siguientes secciones para comprender el modelo de datos de iris:

Requests

Todas las solicitudes para emitir una interacción comparten una misma estructura en el cuerpo (body). A continuación, se muestra un ejemplo:


{

  "payLoad": {
      "Type":"...",
      ... más valores del payload....
  },
  "integrationId": "67c98902c362797495a602c6",
  "processId": "67c98902c362797495a603c1",
  "Destinations":["34638766068"],
  "AutoCreateUser":true,
  "AutoCreateProcess":true
}

donde:

payload

Incluye los datos específicos que se enviarán al cliente. Su contenido varía según el canal y el tipo de interacción:

Lo único común a todos los payloads es el campo Type, que define el tipo de interacción dentro del canal correspondiente. Type no define el canal, sino el tipo de mensaje que viajará por el canal.

integrationId

Este campo indica a través de qué integración se enviará la interacción. Cada integración define, de forma unificada:

Esto permite abstraer la lógica del envío: el emisor solo necesita indicar el integrationId adecuado y el sistema se encarga de gestionar los detalles técnicos del canal y proveedor.

processId

Tal como se explica en 4.1. Introducción a los procesos o conversaciones, las interacciones pueden agruparse dentro de un proceso. Dependiendo del contexto, un proceso puede interpretarse como una conversación con un usuario final, agrupando todos los envíos y respuestas dentro de una misma unidad lógica.

Este campo permite vincular una nueva interacción a un proceso existente. Si se deja en null y el campo AutoCreateProcess está establecido en true, el sistema generará automáticamente un nuevo proceso para esa interacción.

En la respuesta del envío de la interacción, se incluirá siempre el processId en el que fue registrada. Esto permite reutilizar ese identificador en futuras interacciones relacionadas, asegurando que todas formen parte de la misma conversación.

Destinations

Este campo define el conjunto de destinatarios a los que se enviará la interacción. Llamamos destino a un identificador único del usuario final dentro de un canal determinado.

Algunos ejemplos de destinos según el canal:

Aunque el formato acepta un array de destinos, no todos los canales permiten múltiples destinatarios en una misma interacción. Además, algunos proveedores también pueden aplicar sus propias restricciones.

Te recomendamos consultar la documentación específica del canal y del proveedor configurado en la integración para conocer las limitaciones y requisitos de cada caso.

AutoCreateUser

Cada interacción, ya sea emitida o recibida, se asocia siempre a un usuario final en el sistema. Aunque en algunos casos esta asociación puede no ser relevante a nivel funcional, es una relación que el sistema mantiene de forma estructural:
toda interacción pertenece a un proceso, y todo proceso está vinculado a un usuario.

Tal como se detalla en 3.1. Introducción a los usuarios, un usuario en Iris puede tener varios destinos asociados, organizados por tipo (teléfonos, emails, etc.). Por ejemplo, un mismo usuario puede tener múltiples números de teléfono y, al mismo tiempo, varias direcciones de correo electrónico registradas.

El parámetro AutoCreateUser indica al sistema que, si no encuentra un usuario que tenga asociado alguno de los destinos indicados, debe crear automáticamente uno nuevo.
Esto resulta útil para casos en los que el envío de la interacción actúa también como punto de entrada de un nuevo usuario en el sistema.

Si se desactiva esta opción (AutoCreateUser: false) y no se encuentra un usuario con el destino indicado, el sistema rechazará la interacción.

AutoCreateProcess

Este parámetro indica al sistema si debe crear automáticamente un nuevo proceso (o conversación) cuando no se proporciona un valor en el campo processId.

Cuando se establece en true, si el campo processId viene vacío o nulo, el sistema generará un nuevo proceso para asociar la interacción.

Esta opción permite iniciar nuevas conversaciones de forma automática, sin necesidad de haber creado previamente un proceso de manera explícita.

Si se establece en false y no se indica un processId válido, la solicitud será rechazada.

Response

Cuando se realiza una llamada para crear una interacción, el sistema devuelve una respuesta estructurada con información detallada sobre el resultado del procesamiento. Un ejemplo típico es:

{
    "type": "about:blank",
    "title": "OK",
    "status": 200,
    "detail": "Integración enviada a microservicio",
    "instance": null,
    "error": null,
    "payload": {
        "id": "685bc5e5c707c57a2a9d09c6",
        "summary": "{\"subject\":\"\",\"body\":\"\",\"generic\":null}",
        "tenant": "obramat",
        "auditTrail": {
            "created": "2025-06-25T09:48:21.246Z",
            "updated": "2025-06-25T09:48:21.3745474Z",
            "authorId": "67ab5a30265f8a4e73196c0c",
            "updaterId": "67ab5a30265f8a4e73196c0c",
            "history": [
                {
                    "date": "2025-06-25T09:48:21.246Z",
                    "status": "VALIDATION_PENDING",
                    "customStatus": null,
                    "notes": "Interacción registrada"
                },
                {
                    "date": "2025-06-25T09:48:21.3745503Z",
                    "status": "DISPATCH_PENDING",
                    "customStatus": null,
                    "notes": null
                }
            ],
            "providerEvents": []
        },
        "integration": {
            "integrationId": "67c98902c362797495a602c6",
            "integrationName": "RCS-1",
            "integrationTypeId": "684bca2b65457325f7995be8",
            "integrationTypeName": "RCS",
            "integrationTypeProviderId": "684bca2b65457325f7995be9",
            "integrationTypeProviderName": "Sinch"
        },
        "metadata": {},
        "payload": {
            "Type": "text-message-rcs",
            "Text": "Texto del mensaje simple"
        },
        "primaryKey": {},
        "processId": "685bc5e4c707c57a2a9d09c5",
        "users": [
            {
                "id": "67b47f93bb45e1c88f7cca05",
                "metadata": null,
                "name": "Sergio",
                "primaryKey": {
                    "PhoneNumber": [
                        "34638166168"
                    ],
                    "Email": [
                        "inventado1@gmail.com"
                    ]
                }
            }
        ],
        "destinations": [
            {
                "key": "PhoneNumber",
                "value": "34638766068",
                "group": "ungroup",
                "userId": "67b47f93bb45e1c88f7cca05"
            }
        ],
        "attachmentsId": [],
        "direction": "out",
        "status": "DISPATCH_PENDING",
        "customStatus": null,
        "template": null,
        "strategy": null,
        "processSummary": {
            "id": "685bc5e4c707c57a2a9d09c5",
            "metadata": {},
            "primaryKey": {},
            "isClosed": false,
            "isDraft": false,
            "lastDirection": "out"
        },
        "isLastEntry": true
    }
}

status

estado de la solicitud. Se espera siempre que sea 200 si la petición fue admitida. Tenga en cuenta que un 200 no garantiza que la intección se haya enviado correctamente, simplemente indica que se han realizado las validaciones básicas y que la interacción se ha encolado para su procesamiento.

error

en caso de valores de status distintos de 200, array con los errores encontrados.

payload

objeto completo que proporciona información sobre la interacción creada:

id

identificador único de la interacción. es un valor que se le asigna a cada interacción y que es único en todo el sistema

summary

resumen básico de la información que se enviará al usuario. Utilizado comunmente para proporcionar resumenes en listados de envios, etc. solo hace referencia a la información enviada y no al estado u otras componentes del sistema

tenant

tenant asociado a la interaccion

auditTrail

información de tracking de la interacción. incluye tanto el historico de cambios de estado de la interacción dentro de Iris (history) como los eventos capturados del proveedor (providerEvents). Adicionalmente proporciona información de fechas básicas.

integration

proporciona información sobre la integración sobre la que se envío la interacción. esta incluye información de la propia integración, el proveedor que proporciona el servicio y el canal.

metadata

metadatos asociados a la interacción

payload

Contiene los datos principales de la interacción creada: