# 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`) |

### 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"
  }
}
```

| 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. |

### WhatsApp QR

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

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

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `message` | string | Sí | Texto del mensaje a enviar (máximo 4096 caracteres) |

## Respuesta

### Éxito (200 OK)

```json
{
  "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"
  }
}
```

### 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"
  }
}
```

## 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.