# Enviar mensaje e iniciar conversación

Permite enviar un mensaje a un número de teléfono a través de un canal configurado del agente, iniciando una nueva conversación.

## End point

```
POST https://agent.induxsoft.net/svc/{agent_id}/send/{channel}/
```

## Parámetros

### Parámetros de ruta

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `agent_id` | string | ID del agente que enviará el mensaje |
| `channel` | string | Canal a utilizar: `whatsapp` (API oficial) o `whatsappqr` |

### Query parameters

| Parámetro | Tipo | Requerido | Descripción |
|-----------|------|-----------|-------------|
| `to` | string | Sí | Número de teléfono del destinatario en formato E.164 (ej.: +5219982345678). Puede indicar varios números separándolos con (`,`). |

### Headers

```
Authorization: Bearer <Código de seguridad del agente>
Content-Type: application/json
```

## Request body

### WhatsApp API oficial

Cuando `channel` es `whatsapp`, se debe enviar una plantilla aprobada:

```json
{
  "template_id": "uuid de la plantilla",
  "template_vars": {
    "var1": "valor de la variable 1",
    "var2": "valor de la variable 2"
  },
  "queue":"off|on" 
}
```

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `template_id` | string | Sí | UUID de la plantilla aprobada del agente |
| `template_vars` | object | No | Variables de la plantilla. Solo si la plantilla contiene variables. |
| `queue` | string | No | Controla si el mensaje se envía inmediátamente o se pone en cola, el valor predeterminado es 'off'. |

### WhatsApp QR

Cuando `channel` es `whatsappqr`, se envía un mensaje de texto libre:

```json
{
  "message": "Hola, ¿en qué puedo ayudarte?",
  "queue":"off|on" 
}
```

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `message` | string | Sí | Texto del mensaje a enviar (máximo 4096 caracteres) |
| `queue` | string | No | Controla si el mensaje se envía inmediátamente o se pone en cola, el valor predeterminado es 'off'. |

## Respuesta

### Éxito (200 OK)

```json
{
  "success": true,
  "data": {
    "chat_id": "550e8400e29b41d4a716446655440000",
    "message_id": "abc4445454",
    "status": "sent"
  }
}

o bien ( si en `to` indicó más de un número)

{
  "success": true,
  "data": [
    {
      "chat_id": "550e8400e29b41d4a716446655440000",
      "message_id": "abc4445454",
      "status": "sent"
    }
  ]
}
```

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `success` | boolean | Siempre `true` en respuesta exitosa |
| `data.chat_id` | string | UUID de la conversación creada o retomada |
| `data.message_id` | string | UUID del mensaje enviado |
| `data.status` | string | Estado del envío: `sent` (enviado), `pending` (en cola) |

### Error

```json
{
  "success": false,
  "message": "invalid_phone"
}
```

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `success` | boolean | Siempre `false` en error |
| `message` | string | Código del error |

## Ejemplos

### Ejemplo 1: Enviar con WhatsApp API oficial

**Request:**
```bash
curl -X POST \
  'https://agent.induxsoft.net/svc/a1b2c3d4e5f67890abcdef1234567890/send/whatsapp/?to=%2B5219982345678' \
  -H 'Authorization: Bearer eyJhbGc...' \
  -H 'Content-Type: application/json' \
  -d '{
    "template_id": "f9e8d7c6-b5a4-3210-9876-543210fedcba",
    "template_vars": {
      "nombre": "Juan Pérez",
      "fecha": "25 de febrero"
    }
  }'
```

**Response:**
```json
{
  "success": true,
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "message_id": "abc4445454",
    "status": "sent"
  }
}

o bien ( si en `to` indicó más de un número)

{
  "success": true,
  "data": [
    {
      "chat_id": "550e8400e29b41d4a716446655440000",
      "message_id": "abc4445454",
      "status": "sent"
    }
  ]
}
```

### Ejemplo 2: Enviar con WhatsApp QR

**Request:**
```bash
curl -X POST \
  'https://agent.induxsoft.net/svc/a1b2c3d4-e5f6-7890-abcd-ef1234567890/send/whatsappqr/?to=%2B5219982345678' \
  -H 'Authorization: Bearer eyJhbGc...' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Hola, te contactamos de parte de Induxsoft para darte seguimiento a tu solicitud."
  }'
```

**Response:**
```json
{
  "success": true,
  "data": {
    "chat_id": "660f9511-f3ac-52e5-b827-557766551111",
    "message_id": "abc4445454",
    "status": "sent"
  }
}

o bien ( si en `to` indicó más de un número)

{
  "success": true,
  "data": [
    {
      "chat_id": "660f9511-f3ac-52e5-b827-557766551111",
      "message_id": "abc4445454",
      "status": "sent"
    }
  ]
}
```

## Notas

- El número de teléfono debe incluir el código de país con el prefijo `+`
- Para WhatsApp API oficial, solo se pueden usar plantillas previamente aprobadas por Meta
- El `chat_id` retornado se puede usar para obtener el historial de la conversación mediante otros endpoints
- La conversación creada aparecerá en la auditoría de conversaciones del agente
- Si ya existe una conversación abierta con ese número en el mismo canal, se reutiliza el `chat_id` existente en lugar de crear una nueva conversación

# Compatibilidad con servicios que admiten BYOK

## Interfaz de Integración compatible con OpenAI (v1/chat/completions)

Esta interfaz permite conectar los agentes inteligentes de **Induxsoft (IAE)** con cualquier plataforma externa que soporte el protocolo estándar de **OpenAI Chat Completions**. Es la vía recomendada para la integración de orquestadores de voz (Vapi, Retell, Bland AI), sistemas de telefonía VoIP y plataformas de automatización omnicanal.

### 1. Configuración del Servicio

Para integrar el agente en plataformas de terceros, utilice los siguientes parámetros de conexión:

* **Base URL:** `https://agent.induxsoft.net/svc/{agent_id}/proto/openai/v1/`
* **Endpoint:** `https://agent.induxsoft.net/svc/{agent_id}/proto/openai/v1/chat/completions`
* **Método:** `POST`
* **Autenticación:** `Bearer {TU_TOKEN_DE_ACCESO}` (vía Header `Authorization`)

> **Nota:** Sustituya `{agent_id}` por el identificador único del agente asignado en su panel de administración de Induxsoft.

### 2. Especificación del Payload

El servicio procesa solicitudes en formato JSON y responde de manera síncrona una vez que la lógica del agente ha completado su ejecución.

#### Estructura de Solicitud (Request)
El endpoint acepta el esquema estándar de OpenAI. El último mensaje con el rol `user` dentro del arreglo `messages` será procesado como la entrada principal para el agente.

```json
{
  "model": "iae-agent",
  "messages": [
    {
      "role": "user",
      "content": "Hola, ¿podrías confirmar mi cita para mañana?"
    }
  ],
  "stream": false
}
```

#### Estructura de Respuesta (Response)
La respuesta es un objeto JSON estructurado para ser consumido inmediatamente por sintetizadores de voz (TTS) o interfaces de chat.

```json
{
  "id": "iae-msg-unique-hash",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "iae-agent",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Con gusto. Su cita está confirmada para mañana a las 10:00 AM."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}
```

### 3. Comportamiento y Latencia
* **Procesamiento:** El servicio actúa como un puente síncrono. Ejecuta la lógica del agente (incluyendo consultas a bases de datos externas o validaciones de negocio) antes de devolver la respuesta.
* **Manejo de Fillers:** En implementaciones de voz, se recomienda configurar "Fillers" o "Wait Experience" en el orquestador (lado del cliente) para gestionar el tiempo de procesamiento de la lógica de negocio.
* **Errores:** El endpoint devuelve códigos de estado HTTP estándar (401 para errores de autenticación, 404 para agentes inexistentes y 500 para errores en la ejecución de la lógica del agente).

### 4. Compatibilidad BYOK
Este endpoint facilita un modelo de **Bring Your Own Keys (BYOK)**, permitiendo que el cliente utilice servicios de terceros 
(como ElevenLabs para voz o Twilio para telefonía) conectándolos directamente a la inteligencia de Induxsoft a través de un orquestador compatible.


# Uso del servicio como herramienta

El servicio de envío de mensajes vía WhatsApp está habilitado para ser utilizado como una **herramienta dentro del agente**. 
Esto permite que sea invocado automáticamente a partir de una intención.

## Estructura de invocación

Cuando la herramienta es ejecutada, se envía un objeto JSON con múltiples propiedades relacionadas al contexto de la conversación y del agente:

```json
{
  "intention": "Id de la intención",
  "preliminary_answer": "Respuesta preliminar del LLM",
  "original_question": "Pregunta o mensaje original del usuario",
  "reformulated_question": "Pregunta reformulada por el LLM",
  "agent_id": "Id del agente",
  "agent_name": "Nombre del agente",
  "chat_id": "Identificador de la conversación",
  "source_url": "URL origen (opcional)",
  "user_sid": "Token de sesión",
  "user": "Id del usuario",
  "user_name": "Nombre del usuario",
  "data": { ... },
  "params": { ... }
}
```

### Uso de la información

El servicio únicamente utiliza los objetos `data` y `params` para procesar el envío del mensaje. 
El resto de los campos son informativos y corresponden al contexto del agente.

Objeto `data` (principal)

Contiene la información necesaria para el envío del mensaje.

Campos requeridos:

- to: Número telefónico en formato E.164
 - Debe incluir código de país
 - Para México: agregar 1 después del código
 - Ejemplo: +5219611234567
- message: Contenido del mensaje a enviar


Objeto `params` (opcional)

Puede contener parámetros adicionales enviados por la aplicación o configurados en el agente.

Campo soportado:
- to: Número telefónico

#### Regla de prioridad
Si el campo `to` está presente en ambos objetos:

data.to > params.to

Es decir, el valor definido en data tiene prioridad sobre params.`

#### Consideraciones
- El objeto `data` es obligatorio para el correcto funcionamiento de la herramienta
- El servicio ignora cualquier campo fuera de `data` y `params`
- Se recomienda validar el formato del número antes de la invocación
- Token de autorización del agente es requerido, debe indicarse en el encabezado `Authorization`

#### Ejemplo de invocación
```
Request:

curl -X POST \
  'https://agent.induxsoft.net/svc/a1b2c3d4e5f67890abcdef1234567890/send/whatsappqr/' \
  -H 'Authorization: Bearer eyJhbGc...' \
  -H 'Content-Type: application/json' \
  -d '{

      // datos adicionales de la herramienta
    "data":
    {
      "to":"+5219611234567",
      "message":"Hola, prueba de envió"
    },
    "params":
    {

    }
  }

  Response:
  {
    "success": true,
    "data": {
      "chat_id": "550e8400-e29b-41d4-a716-446655440000",
      "message_id": "abc4445454",
      "status": "sent"
    }
  }
```

[Servicio como intención](https://docs.induxsoft.net/es/iae/herramientas/web-send-as-tools.md)