Descripción general y autenticación de la API

La API REST de Ody se encuentra en https://api.ody.co/v1/api y autentica cada solicitud con una clave API enviada como token Bearer. Cree una en Configuración → API para desarrolladores, luego llame a los endpoints a continuación.

Autenticación

Envíe su clave en el encabezado Authorization en cada solicitud:

curl https://api.ody.co/v1/api/contacts \
  -H "Authorization: Bearer ody_live_…"

• Las claves vienen en dos modos: las claves ody_live_… son en vivo, las claves ody_test_… se comportan de manera idéntica pero los envíos de mensajes son simulados (registrados con deliveryStatus: "simulated", nunca transmitidos). Consulte Desarrolle de forma segura con el modo de prueba.
• Una clave faltante, inválida o revocada devuelve 401 unauthenticated.
• Una clave restringida por ámbitos devuelve 403 permission_denied — nombrando el ámbito faltante — cuando llama a un endpoint fuera de sus permisos.
• Cada llamada se ejecuta con los permisos del miembro que creó la clave, solo dentro de ese espacio de trabajo.

Endpoints

Método y ruta	Qué hace	Ámbito requerido
GET /v1/api/contacts	Listar o buscar contactos (?q=, paginado)	contacts:read
POST /v1/api/contacts	Crear un contacto	contacts:write
GET /v1/api/contacts/:id	Obtener los detalles completos de un contacto	contacts:read
PATCH /v1/api/contacts/:id	Actualizar un contacto (solo cambian los campos proporcionados)	contacts:write
DELETE /v1/api/contacts/:id	Eliminar un contacto	contacts:write
GET /v1/api/conversations	Listar conversaciones (?status=open|done, paginado)	conversations:read
GET /v1/api/conversations/:id	Obtener un hilo completo	conversations:read
PATCH /v1/api/conversations/:id	Establecer estado — cuerpo {"status":"open"} o {"status":"done"}	conversations:write
POST /v1/api/messages	Enviar un SMS/MMS (admite Idempotency-Key)	messages:send
GET /v1/api/messages/search	Buscar cuerpos de mensajes y transcripciones (?q=)	conversations:read
GET /v1/api/calls	Listar historial de llamadas y buzón de voz	conversations:read
POST /v1/api/calls	Realizar una llamada saliente de IA — su agente publicado marca	calls:place
GET /v1/api/numbers	Listar los números de su espacio de trabajo	numbers:read
GET /v1/api/numbers/available	Buscar números que puede comprar (?country=, ?startsWith=, ?contains=, ?locality=, ?state=, ?limit=)	numbers:manage
POST /v1/api/numbers	Comprar un número — facturado como una compra dentro de la aplicación (admite Idempotency-Key)	numbers:manage
POST /v1/api/numbers/:e164/connect y …/disconnect	Enrutar un número hacia o desde su agente de IA	agent:manage
GET /v1/api/messaging	Estado de registro 10DLC (step, canText)	numbers:manage
POST /v1/api/messaging/registration	Enviar su negocio + campaña 10DLC (facturado)	numbers:manage
POST /v1/api/messaging/refresh	Volver a verificar y avanzar la revisión del operador 10DLC	numbers:manage
GET/PATCH /v1/api/agent	Leer o actualizar la configuración de su agente de IA (borrador)	agent:manage
POST /v1/api/agent/publish	Publicar la configuración de su agente en vivo	agent:manage
GET /v1/api/webhook-events	Listar tipos de eventos de webhook a los que se puede suscribir	webhooks:manage
GET/POST /v1/api/webhooks y /v1/api/webhooks/:id…	Administrar endpoints de webhook salientes	webhooks:manage
GET /v1/api/openapi.json	La especificación OpenAPI 3.1	ninguno

Los endpoints de lista se paginan con ?limit= y ?cursor= — consulte Paginación, idempotencia y manejo de errores.

Contactos

POST /v1/api/contacts necesita al menos un campo de identidad: firstName, lastName, company, un teléfono o un correo electrónico. Los teléfonos y correos electrónicos aceptan una cadena simple ("phone": "+15125550123") o arreglos etiquetados completos ("phones": [{"value": "+15125550123", "label": "work"}]). En PATCH, solo cambian los campos que proporcione; phones, emails, notes, properties y tags se reemplazan por completo cuando se suministran.

Envío de un mensaje

POST /v1/api/messages acepta un conversationId existente o un número de teléfono de destinatario en to (formato E.164). Con to, Ody elige el número de envío de su espacio de trabajo (o respeta un from que usted posee), crea la conversación si es necesario y enhebra el mensaje. Agregue hasta 10 mediaUrls públicamente accesibles para MMS:

curl https://api.ody.co/v1/api/messages \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{"to":"+15125550123","body":"Your order shipped!"}'

Un espacio de trabajo sin un número de teléfono activo recibe 409 failed_precondition. Los reintentos con la misma Idempotency-Key dentro de las 24 horas reproducen la primera respuesta en lugar de enviar dos veces.

Números, mensajes de texto, llamadas de IA y su agente

La API también puede operar una línea telefónica de principio a fin: buscar y comprar números, registrar mensajes de texto 10DLC, configurar y publicar su agente de IA, enrutar números hacia él y realizar llamadas salientes de IA. Estos endpoints utilizan tres ámbitos propios — numbers:manage (Comprar números y 10DLC), calls:place (Realizar llamadas de IA) y agent:manage (Administrar agente de IA) — y todo lo que hacen se registra en su cuenta exactamente como si lo hubiera hecho en la aplicación, con la misma facturación y reglas. Consulte Comprar números y registrar mensajes de texto a través de la API y Realizar llamadas de IA y administrar Astra a través de la API.

Errores, IDs de solicitud y límites de tasa

Cada error utiliza un formato uniforme, y cada respuesta (éxito o error) lleva un encabezado X-Request-Id — cítelo cuando se ponga en contacto con soporte:

{ "error": { "code": "not_found", "message": "Contact not found", "requestId": "req_…" } }

Cada clave obtiene 600 solicitudes/minuto con los encabezados estándar RateLimit-*. Detalles en Límites de tasa de la API y mejores prácticas y Paginación, idempotencia y manejo de errores.

Artículos relacionados

• Obtener su clave API de Ody
• Recibir webhooks y verificar firmas
• Paginación, idempotencia y manejo de errores
• Inicio rápido del SDK: TypeScript y Python