Mensajes y conversaciones #

La API de Mensajes le permite enviar un mensaje a cualquier contacto, leer una conversación, corregir o eliminar un mensaje que ya envió, reaccionar a uno, extraer un hilo completo de sesión de chat, exportar una transcripción y marcar chats como leídos o no leídos, todo sin abrir la bandeja de entrada.

Todas las rutas en esta página son relativas a la URL base https://api.youraiconnector.com/v1. Cada solicitud requiere su clave de API; consulte Autenticación para ver la lista completa de formas de enviarla. Los ejemplos a continuación utilizan el encabezado X-API-Key, y un ejemplo de cURL muestra también el formato de consulta ?apiKey=.

Cómo funciona la entrega: El envío de un mensaje no espera a que llegue. La API acepta su mensaje, responde inmediatamente con un ID de mensaje y luego lo entrega en segundo plano a través del canal del contacto (WhatsApp, SMS, Instagram, etc.). Para realizar un seguimiento de si un mensaje se entregó o leyó realmente, escuche las actualizaciones de estado con Webhooks; no realice sondeos (polling). La respuesta de envío solo confirma que el mensaje fue aceptado.

Enviar un mensaje #

Hay dos formas de enviar. Elija la que mejor se adapte a cómo identifica actualmente al contacto:

• Enviar por ID de contacto: usted ya conoce el ID del contacto (por ejemplo, creó el contacto a través de la API u lo obtuvo de un webhook). Use POST /contacts/{contactId}/send-message.
• Enviar por identidad de contacto: usted conoce el número de teléfono, el ID de Instagram, etc., del contacto, pero no su ID interno. Use POST /contacts/send y deje que la plataforma encuentre el contacto correcto.

Ambos ponen el mensaje en cola de la misma manera y lo entregan en el canal en el que se encuentre el contacto. Usted no elige el transporte; la plataforma enruta los contactos de WhatsApp a través de WhatsApp, los contactos de SMS a través de SMS, y así sucesivamente.

Ambas también solo encuentran contactos que ya existen. Ninguna de las llamadas crea uno: un ID o una identidad que no coincide devuelve un 404, no se convierte en un nuevo contacto. Por lo tanto, si le escribes a alguien por primera vez, primero crea el contacto con POST /contacts o, en WhatsApp Web, utiliza Enviar directamente a un número de WhatsApp Web a continuación, lo cual crea el contacto en la misma llamada.

Enviar por ID de contacto #

POST /contacts/{contactId}/send-message

En LinkedIn, un mensaje que envíes de esta manera, o desde la bandeja de entrada, se entrega incluso mientras una persona está gestionando el hilo desde el lado de LinkedIn. Las propias respuestas de la IA y sus seguimientos se retienen en dicho hilo. Una respuesta retenida se elimina del chat en lugar de mostrarse como fallida, ya que no se envió nada y no se utiliza ningún crédito. La última respuesta de la IA antes de que pase un hilo a una persona se sigue entregando.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi! Your appointment is confirmed for tomorrow at 10:00."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/send-message",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi! Your appointment is confirmed for tomorrow at 10:00.",
    }),
  }
);
const data = await res.json();
console.log(data.messageId);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/send-message",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Hi! Your appointment is confirmed for tomorrow at 10:00."},
)
print(res.json()["messageId"])

Respuesta (200 OK):

{
  "success": true,
  "messageId": "aB3dE5fG7hI9jK1lM2nO",
  "contactId": "contact123",
  "channel": "whatsapp",
  "message": "Message created successfully. Delivery is being processed."
}

Enviar por identidad de contacto #

POST /contacts/send

Utilice esto cuando no tenga el ID interno del contacto. Proporcione el body del mensaje más o bien un contact_id, o bien un channel junto con el campo de identidad que coincida con ese canal.

Qué canales pueden resolverse mediante identidad. Solo seis de los 14 aceptan un campo de identidad en lugar de un contact_id: whatsapp, whatsapp_web y sms se buscan mediante phone_number, instagram mediante instagram_id, messenger mediante messenger_id, y telegram mediante telegram_user_id. Los otros ocho — instagram_private, chat-widget, custom, email, line, imessage, linkedin y viber — no tienen una identidad pública que buscar, por lo que enviar a través de esos canales requiere contact_id; pasar solo channel devuelve un 400 indicando que se requiere contact_id.

cURL (usando el formato de consulta ?apiKey=)

curl -X POST "https://api.youraiconnector.com/v1/contacts/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "body": "Hi! Your appointment is confirmed."
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel: "whatsapp",
    phone_number: "+31612345678",
    body: "Hi! Your appointment is confirmed.",
  }),
});
const data = await res.json();
console.log(data.message_id, data.channel);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/send",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "channel": "whatsapp",
        "phone_number": "+31612345678",
        "body": "Hi! Your appointment is confirmed.",
    },
)
data = res.json()
print(data["message_id"], data["channel"])

Respuesta (201 Created):

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp"
}

Por qué un mensaje podría ser rechazado: Un contacto con el modo “no molestar” o privado activado no puede recibir mensajes salientes; la solicitud falla con un 422. Si ningún contacto coincide con el ID o la identidad que proporcionó, obtendrá un 404.

Envío en WhatsApp Web: variaciones y protección contra ráfagas #

Dos aspectos se aplican a body cuando el contacto está en WhatsApp Web.

Las llaves de Spintax se expanden por envío. Un body de {Hi|Hello|Hey} there, quick question se envía como uno de los tres saludos, elegido para ese envío; las llaves nunca llegan al contacto. Úselo para darle a cada contacto un mensaje de apertura diferente desde el mismo código de integración. El texto sin llaves se envía exactamente como está escrito.

Se rechazan las ráfagas de mensajes de apertura idénticos. Si se envían diez mensajes de apertura casi idénticos desde un número de WhatsApp Web en el transcurso de una hora a contactos que nunca le han escrito, los siguientes no se entregarán: el envío se acepta como de costumbre (usted sigue recibiendo un messageId) y el mensaje se queda con status: "failed" y error_code: "opener_burst", con un motivo legible para el cliente. Reintentar con el mismo texto no ayuda: varíe el texto, espere una hora y vuelva a enviar. Las respuestas dentro de conversaciones existentes nunca se ven afectadas. La razón se encuentra en Los abridores idénticos provocan restricciones en los números.

Enviar directamente a un número de WhatsApp Web #

POST /whatsapp-web/send

Envía a un número de teléfono en WhatsApp Web sin buscar primero un contacto. Si el número aún no es un contacto, se crea en la misma llamada, con la IA desactivada para él, de modo que el mensaje parezca enviado manualmente y ningún asistente tome el control de la conversación después. Un contacto existente se reutiliza tal cual.

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-web/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "message": "Hi Alex, your quote is ready."
  }'

Una llamada exitosa responde 202:

{ "success": true, "queued": true, "contactId": "abc123" }

202 significa aceptado, aún no entregado. Fuera del horario activo, el envío se retiene y sale en el siguiente intervalo permitido, a menos que hayas pasado ignoreActiveHours. Consulta el estado del mensaje con Listar los mensajes de un contacto usando el contactId que obtuviste aquí.

Cuando no se procesa:

Una segunda llamada para el mismo contacto mientras un envío retenido sigue esperando responde 409, por lo que nunca se acumula una cola detrás de una persona.

Registrar una nota en una conversación #

POST /contacts/notes

Añade una línea a la conversación de un contacto sin enviarla. Úsala para añadir contexto que tu equipo y la IA deban tener, pero que el contacto nunca deba recibir: un resumen de una llamada telefónica que acaba de realizar tu agente de voz, un comentario de tu CRM o una nota de un compañero. Funciona en todos los canales (WhatsApp, SMS, Instagram, Messenger, Telegram, el widget de chat, canales personalizados, etc.).

Qué sucede con una nota:

• Aparece en el chat de la bandeja de entrada como una tarjeta amarilla de Nota, con el autor si indicaste uno.
• La IA la lee como parte del historial de la conversación, marcada como nota interna, por lo que su próxima respuesta la tendrá en cuenta.
• Nunca se envía al contacto, no consume créditos de mensajes y no activa nada: ni respuesta de la IA, ni automatización, ni webhook, ni notificación, ni insignia de no leído. No pausa la IA y no cuenta como una respuesta de tu equipo.

Busca el contacto de la misma manera que en Enviar por identidad de contacto: ya sea mediante su ID o mediante un channel más el identificador correspondiente. Una nota solo se envía a un contacto que ya existe; si no hay coincidencias, se produce un 404.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/notes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "author": "Voice agent",
    "body": "Voice call, 3:12. Asked about knee surgery waiting times, prefers a call back on Tuesday morning.",
    "external_id": "call_8f2k1"
  }'

Respuesta (201, o 200 con duplicate: true cuando la external_id ya se había registrado)

{
  "success": true,
  "messageId": "note_4c1f0e...",
  "contactId": "contact123"
}

Una nota aparece en Listar los mensajes de un contacto con type: "note".

Generar un borrador de respuesta con la IA #

POST /contacts/{contactId}/draft-reply

Solicita al agente de IA que gestiona una conversación que escriba la siguiente respuesta y te devuelve el texto. No se envía nada. Es el mismo borrador que escribe el botón Generar respuesta en la bandeja de entrada: el agente utiliza su configuración, su base de conocimientos y la conversación hasta el momento, y responde en el idioma del contacto. Úsalo para poner a un humano (o a tu propia aplicación) entre la IA y el contacto: obtén el borrador, muéstralo para su aprobación y luego envíalo con Enviar por ID de contacto, modificado o tal como está.

• El borrador lo escribe el agente asignado al contacto. Un contacto que aún no tiene agente recibe el agente que respondería a su siguiente mensaje.
• Mientras redacta, el agente no ejecuta ninguna herramienta ni función, por lo que no se realiza ninguna reserva, etiqueta, transferencia u otra acción.
• No se almacena nada en la conversación y el contacto no ve nada.
• Un borrador cuesta los mismos créditos que una respuesta de IA de ese agente en esta conversación, y nada cuando tu propia clave de IA está conectada.
• La conversación necesita al menos un mensaje.

Todos los campos del cuerpo son opcionales; un cuerpo vacío (o sin cuerpo) redacta la siguiente respuesta.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/draft-reply" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "Offer Tuesday at 3pm for the consultation" }'

Respuesta (200)

{
  "success": true,
  "contact_id": "contact123",
  "draft": "Hi Sara, Tuesday at 3pm works for the consultation. Shall I put you down for it?"
}

Un 400 significa que la conversación aún no tiene mensajes, que tus créditos se agotaron o que el contacto no tiene un agente o campaña desde la cual redactar (el error indica cuál). Un 404 significa que el contacto no existe o que la clave de un miembro del equipo está limitada a contactos que no puede ver. La clave o el miembro del equipo necesita permiso para editar mensajes.

¿Usas un cliente de IA a través de MCP? La misma acción está disponible como la herramienta generate_reply_draft.

Listar los mensajes de un contacto #

GET /contacts/{contactId}/messages

Devuelve los mensajes de un contacto, del más reciente al más antiguo, con paginación basada en cursor.

Nota sobre el filtrado y la paginación: Los filtros filter y direction se aplican a cada página después de ser leída, por lo que una página filtrada puede contener menos elementos que limit. El next_cursor sigue avanzando a través de la conversación completa, así que continúe paginando hasta que next_cursor sea null.

cURL

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&direction=inbound" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ limit: "50", direction: "inbound" });
const res = await fetch(
  `https://api.youraiconnector.com/v1/contacts/contact123/messages?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.messages, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"limit": 50, "direction": "inbound"},
)
data = res.json()
print(data["messages"], data["next_cursor"])

Respuesta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T10:00:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ],
  "next_cursor": "cD4eF6gH8iJ0kL2mN3oP"
}

Campos del mensaje #

Descargar el archivo adjunto de un mensaje #

POST /chat-exports/media/download-url

Le proporciona un nuevo enlace de descarga para el archivo adjunto a un mensaje: una imagen, nota de voz, vídeo o documento. El enlace funciona durante 1 hora. Úselo cuando desee guardar archivos adjuntos en otro lugar (por ejemplo, archivar CV o notas de voz enviadas por un contacto), o cuando el media_url de un mensaje o un webhook de mensaje nuevo ya no se abra.

Para encontrar mensajes con archivos adjuntos, enumere los mensajes de un contacto con filter=media. El id de cada mensaje y el ID del contacto conforman el messagePath.

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/media/download-url" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"}'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/chat-exports/media/download-url", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ messagePath: "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO" }),
});
const { data } = await res.json();
console.log(data.url); // download the file within the hour

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/chat-exports/media/download-url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"},
)
file_url = res.json()["data"]["url"]

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "url": "https://storage.googleapis.com/...",
    "expiresInMs": 3600000
  }
}

¿Utiliza un cliente de IA a través de MCP? La misma acción está disponible como la herramienta get_chat_media_download_url.

Listar sesiones de chat #

Una sesión de chat es una ventana de conversación con un contacto. Se abre con el primer mensaje entrante cuando no hay ninguna sesión abierta y se cierra automáticamente 48 horas después del último mensaje entrante del contacto (cada nuevo mensaje entrante pospone el cierre otras 48 horas). Que la IA concluya un chat no cierra la sesión; solo activa el webhook de Chat concluido. Las sesiones son la forma en que se pagina un historial largo en conversaciones legibles en lugar de una lista interminable.

Sesiones recientes de todos los contactos #

GET /chat-sessions/recent

Devuelve las sesiones que comenzaron en las últimas X horas, de la más reciente a la más antigua, en todos los contactos de la cuenta.

cURL

curl "https://api.youraiconnector.com/v1/chat-sessions/recent?hours=24&status=ChatSessionClosed" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ hours: "24", status: "ChatSessionClosed" });
const res = await fetch(`https://api.youraiconnector.com/v1/chat-sessions/recent?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.data.total_sessions, data.data.sessions);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-sessions/recent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"hours": 24, "status": "ChatSessionClosed"},
)
data = res.json()["data"]
print(data["total_sessions"], data["sessions"])

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_sessions": 2,
    "sessions": [
      {
        "session_id": "session456",
        "contact_id": "contact123",
        "contact_name": "Jane Doe",
        "contact_phone": "+31612345678",
        "contact_email": "jane@example.com",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}

Todas las sesiones de un contacto #

GET /chat-sessions/{contactId}

Devuelve todas las sesiones de chat de un solo contacto. Los mismos parámetros status, limit y includeMessages que arriba; hours no se aplica aquí.

cURL

curl "https://api.youraiconnector.com/v1/chat-sessions/contact123?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "contact_id": "contact123",
    "contact_name": "Jane Doe",
    "total_sessions": 2,
    "sessions": [
      {
        "id": "session456",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}

Los nombres de los campos de ID de sesión difieren entre los dos endpoints. La lista de sesiones recientes lo llama session_id (también contiene los detalles del contacto, ya que las sesiones provienen de muchos contactos); la lista por contacto lo llama id. Cualquiera de los dos valores es lo que usted pasa como {sessionId} al recuperar el hilo completo a continuación.

Cuando includeMessages=true, cada sesión obtiene una matriz messages cuyas entradas contienen id, body, direction, timestamp, type, channel y status.

Obtener un hilo de sesión de chat #

GET /contacts/{contactId}/chat-sessions/{sessionId}/messages

Una sesión de chat agrupa los mensajes de un contacto en una única ventana de conversación. Este endpoint devuelve el hilo completo de una sola sesión, del más antiguo al más reciente, junto con los metadatos de la sesión. Puede encontrar los ID de sesión de un contacto a través de los endpoints de sesiones de chat.

cURL

curl "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.session, data.messages);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["session"], data["messages"])

Respuesta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "session": {
    "id": "session456",
    "status": "ChatSessionClosed",
    "start_date_time": "2026-06-01T09:55:00.000Z",
    "end_date_time": "2026-06-01T10:20:00.000Z",
    "tag": "Booking enquiry"
  },
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T09:55:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ]
}

El objeto session informa sobre status (ChatSessionOpened mientras está activa, ChatSessionClosed una vez finalizada), start_date_time, end_date_time y un tag legible por humanos. La matriz messages utiliza los mismos campos de mensaje que el endpoint de lista.

Editar, eliminar y reaccionar a mensajes #

Estos endpoints cambian un mensaje después de haber sido enviado. Dos de ellos se comunican con el canal del contacto además de con su propia copia, así que lea la introducción de la sección antes de configurarlos; lo que es posible depende totalmente del canal en el que se encuentre la conversación.

Qué permite cada canal

En cualquier otro canal —la API de WhatsApp Business, SMS, Instagram, Messenger, correo electrónico, LINE, canales personalizados—, una eliminación sigue quitando el mensaje de su bandeja de entrada, pero el contacto conserva su copia, y editar o reaccionar no es posible en absoluto.

Editar un mensaje #

POST /contacts/{contactId}/messages/{messageId}/edit

Reescribe un mensaje que ya envió, tanto en el dispositivo del contacto como en su copia.

A diferencia de la eliminación, esto falla de forma notoria cuando el canal lo rechaza: obtienes un 409 y tu copia se queda exactamente como la tiene el contacto, porque mostrar una edición que nunca recibieron desincronizaría ambas partes. El campo edit_reason te indica el motivo: el periodo de edición del canal ha finalizado, el canal está desconectado, el mensaje tiene un archivo adjunto que el canal no puede editar (media_not_editable: en WhatsApp Web solo se pueden editar mensajes de texto, no el texto debajo de una foto, video o archivo), o algo más salió mal.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Sorry - I meant Thursday at 3pm." }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ body: "Sorry - I meant Thursday at 3pm." }),
  }
);
const data = await res.json();
console.log(data.edited, data.edit_reason);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Sorry - I meant Thursday at 3pm."},
)
data = res.json()
print(data.get("edited"), data.get("edit_reason"))

Respuesta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "edited": true,
  "edit_reason": "edit_dispatched"
}

Si el canal no acepta la edición, obtendrá un 409 en su lugar y nada habrá cambiado:

{
  "success": false,
  "error": "The message could not be edited",
  "edit_reason": "channel_disconnected"
}

Un mensaje que ya ha sido eliminado, un canal que no permite editar en absoluto y un mensaje demasiado antiguo para su canal devuelven 400: la solicitud nunca llega al canal.

Eliminar un mensaje #

DELETE /contacts/{contactId}/messages/{messageId}

Elimina el mensaje de su conversación y, cuando el canal lo permite, también retira la copia del contacto. No requiere cuerpo de solicitud.

Esto siempre responde 200 cuando el mensaje existía, incluso si la copia del contacto no pudo ser retirada; su copia sí ha desaparecido, por lo que un error sería engañoso. Lea los tres campos en la respuesta para informar al usuario de lo que realmente sucedió:

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.revoked, data.revoke_reason);

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["revoked"], data["revoke_reason"])

Respuesta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "revoke_supported": true,
  "revoked": true,
  "revoke_reason": "revoke_dispatched"
}

Los mensajes eliminados no se borran del historial de la conversación. Permanecen en GET /contacts/{contactId}/messages con is_deleted: true y un body y media_url vacíos.

Eliminar varios mensajes a la vez #

POST /contacts/{contactId}/messages/bulk-delete

Borra un lote de mensajes solo de tu lado. Los cuerpos y archivos adjuntos se vacían, pero no se retira nada en el dispositivo del contacto; para retirar también un mensaje, elimínalo uno a uno con el endpoint de mensaje único anterior.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message_ids": ["msg_1", "msg_2"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message_ids: ["msg_1", "msg_2"] }),
  }
);
console.log((await res.json()).deleted);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["msg_1", "msg_2"]},
)
print(res.json()["deleted"])

Respuesta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "deleted": 2
}

Reaccionar a un mensaje #

POST /contacts/{contactId}/messages/{messageId}/react

Coloca tu propia reacción con emoji en un mensaje, o retírala enviando una cadena vacía. Las reacciones del propio contacto nunca se ven afectadas.

Al igual que la edición, esto falla en lugar de mostrar una reacción que el contacto nunca recibió, y el error te indica si vale la pena reintentarlo:

• 422 — nunca se puede entregar en esta conversación: el canal no admite reacciones, el mensaje no tiene un ID del lado del canal, o el emoji está fuera del conjunto permitido por ese canal.
• 409 — el canal no estuvo disponible momentáneamente. Un reintento podría funcionar.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "👍" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ emoji: "👍" }),
  }
);
const data = await res.json();
console.log(data.reactions);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"emoji": "👍"},
)
print(res.json()["reactions"])

Respuesta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "reaction_supported": true,
  "reaction_reason": "reaction_dispatched",
  "reactions": [
    {
      "emoji": "👍",
      "from_phone_number": "+31612345678",
      "from_me": true,
      "reacted_at": "2026-06-01T10:05:00.000Z"
    }
  ]
}

La matriz reactions es el conjunto completo de reacciones que hay ahora en el mensaje, las tuyas y las del contacto. En un 409 o 422 se devuelve sin cambios, por lo que un cliente que renderice directamente desde ella nunca mostrará una reacción que no se haya entregado.

Calificar o destacar un mensaje #

PATCH /contacts/{contactId}/messages/{messageId}

Califica un mensaje con pulgar arriba o pulgar abajo y/o lo marca como importante. Esto es contabilidad solo de tu lado; no se envía nada al contacto.

Envíe al menos uno de los dos, o recibirá un 400. Solo se escribe lo que usted envía, por lo que marcar un mensaje con estrella nunca borra su calificación y viceversa; además, la respuesta solo devuelve los campos que usted envió.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "score": 1, "is_important": true }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1", {
  method: "PATCH",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ score: 1, is_important: true }),
});

Python

import requests

requests.patch(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"score": 1, "is_important": True},
)

Respuesta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "score": 1,
  "is_important": true
}

Marcar mensajes como leídos #

Puede borrar el estado de no leído ya sea para mensajes específicos o para toda la conversación.

Marcar mensajes específicos como leídos #

POST /contacts/{contactId}/messages/mark-read

Pase los ID de los mensajes que desea marcar como leídos.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message_ids: ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"],
    }),
  }
);
const data = await res.json();
console.log(data.marked_read);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]},
)
print(res.json()["marked_read"])

Respuesta (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "marked_read": 2
}

Marcar todo el chat como leído #

POST /contacts/{contactId}/mark-read

Borra el distintivo de no leído de toda la conversación del contacto en la bandeja de entrada. No se requiere cuerpo de solicitud.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-read" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

Respuesta (200 OK):

{
  "success": true,
  "contact_id": "contact123"
}

Marcar todo el chat como no leído #

POST /contacts/{contactId}/mark-unread

Vuelve a colocar la insignia de no leído en la conversación; es útil cuando alguien de su equipo abrió un chat pero lo está devolviendo. No se requiere cuerpo de solicitud.

Este es un indicador exclusivo de la bandeja de entrada: no cambia cuándo se leyó la conversación por última vez, por lo que no se envía ningún recibo de lectura al contacto en los canales que los admiten.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-unread" \
  -H "X-API-Key: YOUR_API_KEY"

Respuesta (200 OK):

{
  "success": true,
  "contact_id": "contact123"
}

Exportar una conversación #

Las exportaciones le ofrecen una conversación completa como una transcripción legible, en lugar de pasar páginas de mensajes. Cada punto final de exportación acepta un filter de all (predeterminado), text, media o tool_use, que coincide con el filtro de la lista de mensajes.

Exportar el chat de un contacto #

GET /chat-exports/{contactId}

cURL

curl "https://api.youraiconnector.com/v1/chat-exports/contact123?format=json" \
  -H "X-API-Key: YOUR_API_KEY"

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-exports/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"format": "json"},
)
print(res.json()["data"]["messages"])

Respuesta con format=json (200 OK):

{
  "success": true,
  "data": {
    "contact": {
      "id": "contact123",
      "name": "Jane Doe",
      "phone": "+31612345678",
      "email": "jane@example.com"
    },
    "messages": [
      {
        "body": "Hi! I have a question about my order.",
        "direction": "inbound",
        "timestamp": "2026-06-01T09:55:00.000Z",
        "type": "text",
        "media_url": null,
        "media_content_type": null,
        "name": null,
        "args": null
      }
    ]
  }
}

Con format=txt (el predeterminado), data es en su lugar un enlace de descarga al archivo de transcripción generado:

{
  "success": true,
  "data": "https://storage.googleapis.com/.../chat-export-contact123-....txt"
}

El enlace de descarga tiene una duración limitada. Obtenga el archivo tan pronto como reciba el enlace en lugar de almacenarlo; solicite una nueva exportación cuando necesite la transcripción nuevamente.

Exportar todas las conversaciones recientes #

GET /chat-exports/recent

Exporta las conversaciones de todos los contactos que estuvieron activos en las últimas X horas, en una sola llamada.

cURL

curl "https://api.youraiconnector.com/v1/chat-exports/recent?hours=24&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_contacts": 2,
    "exports": [
      {
        "contactId": "contact123",
        "contactName": "Jane Doe",
        "phoneNumber": "+31612345678",
        "email": "jane@example.com",
        "messageCount": 12,
        "chatExport": "Acme Export - Jane Doe\nPhone: +31612345678\n..."
      }
    ]
  }
}

Con format=txt la respuesta es el archivo de texto en sí, enviado como una descarga en lugar de JSON.

Esta llamada obtiene el historial completo de cada contacto coincidente, así que mantenga hours y limit moderados en cuentas con mucha actividad.

Enviar una transcripción por correo electrónico al contacto #

POST /chat-exports/{contactId}/email

Envía al contacto su propia transcripción de la conversación por correo electrónico: el flujo “enviarme este chat por correo”, gestionado desde su propio sistema.

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/contact123/email" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Here is a copy of our chat, as promised." }'

Respuesta (200 OK):

{
  "success": true,
  "data": {
    "via": "transactional",
    "recipientEmail": "jane@example.com",
    "messageCount": 42,
    "omittedCount": 0
  }
}

omittedCount le indica cuántos de los mensajes más antiguos se omitieron para mantener el correo electrónico con una longitud razonable. Un 200 significa que la transcripción se generó y se puso en cola para su envío, no que haya llegado a la bandeja de entrada todavía.

Pausar o reanudar la IA para un contacto #

PUT /contacts/{contactId}

Establece is_bot_active en false para detener las respuestas de la IA a un contacto, y vuelve a true para devolver la conversación. Este es el interruptor de control que necesitas cuando un humano interviene en una conversación: los mensajes salientes que envías con la API se siguen entregando mientras el bot está pausado.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/contacts/contact123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_bot_active": false }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/contacts/contact123", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ is_bot_active: false }),
});

Python

import requests

requests.put(
    "https://api.youraiconnector.com/v1/contacts/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_bot_active": False},
)

Respuesta

{
  "success": true,
  "contact_id": "contact123"
}

Pausar como parte de la respuesta

Si un humano va a tomar el control enviando una respuesta, puede pausar el bot en la misma solicitud en lugar de realizar una segunda llamada. POST /contacts/{contactId}/send-message acepta estas banderas opcionales:

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi, Sarah here - taking over from the assistant.",
    "pauseBot": true,
    "clearIncompleteReply": true,
    "human_reply": true
  }'

La respuesta incluye "botPaused": true cuando se aplicó la pausa.

Marcar un contacto como privado con POST /contacts/bulk-flag también pausa el bot para él. Consulta Contactos para ver la lista completa de campos.

Construyendo tu propia bandeja de entrada #

Todo lo que necesita una bandeja de entrada está en esta página y en Contactos:

Para actualizaciones en tiempo real, suscríbete a los eventos New Message, Replies, Human Alerted y Chat Concluded con Webhooks en lugar de consultar esta API mediante un temporizador.

Errores de la API de mensajes #

Los endpoints de mensajes devuelven el sobre de error estándar:

{
  "success": false,
  "error": "Contact not found"
}

Los códigos compartidos que puede devolver cualquier endpoint — 401, 403 (su plan no incluye acceso a la API), 429 (límite de tasa) y 500 — se enumeran con orientación sobre reintentos en Errores y paginación.

Próximos pasos #

• Webhooks: reciba actualizaciones del estado de entrega en lugar de realizar sondeos.
• Contactos: cree y busque los contactos a los que envía mensajes.
• Citas: reserve y gestione citas para sus contactos.