REST 1.0.0

API publica v1

Referencia HTTP server-to-server para leer estado operativo actual, reconciliar cambios y enviar plantillas WhatsApp aprobadas.

Base URL

https://<deployment>.convex.site/api/v1

Configuracion minima

Crea una API key desde el dashboard del agente, asigna solo los scopes necesarios y guardala como secreto de servidor.

Abre el agente en Oriann y entra a Settings / API keys.
Selecciona scopes segun la operacion que consumira tu sistema.
Usa Authorization: Bearer <api_key> en cada request. Las llaves empiezan con oriann_sk_.
Para rotar una key sin corte, crea una sustituta con los scopes minimos, despliegala, verifica uso y revoca la anterior. El secreto solo se muestra al crearla.

Auth, scopes y rate limits

Las API keys estan ligadas a un agente y pueden revocarse desde el dashboard.

Campo	Tipo	Regla	Descripcion
Authorization	Bearer token	required	Header requerido en todas las llamadas.
limit	integer	optional	Default 50, maximo 100 en endpoints paginados.
cursor	string	optional	Cursor devuelto por la respuesta anterior.
RateLimit-*	response headers	optional	Limite, restante y reset Unix del bucket autenticado.

Read endpoints

120/min

Template sends

30/min

Pre-auth

por source

Sincronizacion de Tickets

Los webhooks reducen latencia; REST es la fuente autoritativa para estado actual.

Haz backfill de /tickets siguiendo cursor hasta hasMore=false.
Procesa webhooks de forma idempotente y guarda su ticketVersion.
Reconcilia /ticket-changes desde la ultima position confirmada y aplica tambien ticket_tombstone. Envia el valor de pagination.after como el siguiente after.

Un filtro de atributo usa juntos attributeId, attributeType, attributeOperator y attributeValue. Se acepta como maximo un atributo por request; string, enum y boolean sólo admiten eq.

List current Ticket snapshots

Backfill paginado del estado actual. Filtra por status, conversationId, flowId, rango updated o un atributo tipado.

GET/ticketsscope: tickets:read

bash

curl "https://<deployment>.convex.site/api/v1/tickets?status=open&limit=50" \
  -H "Authorization: Bearer $ORIANN_API_KEY"

Get current Ticket snapshot

Obtiene el Snapshot actual autoritativo. V1 no publica historial ni /versions.

GET/tickets/{ticketId}scope: tickets:read

bash

curl "https://<deployment>.convex.site/api/v1/tickets/<ticket_id>" \
  -H "Authorization: Bearer $ORIANN_API_KEY"

Reconcile Ticket changes

Lee cambios ordenados por position, incluidos tombstones. Guarda la ultima position confirmada y pagina hasta hasMore=false.

GET/ticket-changesscope: tickets:read

bash

curl "https://<deployment>.convex.site/api/v1/ticket-changes?after=<last_position>&limit=100" \
  -H "Authorization: Bearer $ORIANN_API_KEY"

List contacts

Lista contactos del agente asociado a la API key.

GET/contactsscope: contacts:read

bash

curl "https://<deployment>.convex.site/api/v1/contacts?limit=50" \
  -H "Authorization: Bearer $ORIANN_API_KEY"

List conversations

Filtra conversaciones por canal y estado CRM.

GET/conversationsscope: conversations:read

bash

curl "https://<deployment>.convex.site/api/v1/conversations?channel=whatsapp&crmStatus=open" \
  -H "Authorization: Bearer $ORIANN_API_KEY"

List messages

Lista mensajes de una conversacion del agente.

GET/conversations/{conversationId}/messagesscope: messages:read

bash

curl "https://<deployment>.convex.site/api/v1/conversations/<conversation_id>/messages?limit=50" \
  -H "Authorization: Bearer $ORIANN_API_KEY"

List WhatsApp templates

Lista plantillas WhatsApp sincronizadas. Sin query conserva el maximo historico de 200; usa limit/cursor para integraciones nuevas.

GET/templatesscope: templates:read

bash

curl "https://<deployment>.convex.site/api/v1/templates?limit=50" \
  -H "Authorization: Bearer $ORIANN_API_KEY"

Send a WhatsApp template

Envia una plantilla aprobada y enviable. Requiere Idempotency-Key en header y usa parameters: objetos para variables named o arrays para variables positional.

POST/template-sendsscope: templates:send

bash

curl "https://<deployment>.convex.site/api/v1/template-sends" \
  -H "Authorization: Bearer $ORIANN_API_KEY" \
  -H "Idempotency-Key: crm-message-123" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNormalized": "5215512345678",
    "templateName": "order_update",
    "templateLanguage": "es_MX",
    "parameters": {
      "body": { "customer_name": "Ana" },
      "header": { "image": { "id": "wam_media_id" } },
      "buttons": [{ "index": 0, "text": "tracking-123" }]
    }
  }'

Compatibilidad y orden

V1 conserva aliases historicos mientras los consumidores migran al modelado REST canonico.

GET /messages?conversationId=... sigue disponible, pero esta deprecado a favor de la relacion /conversations/{conversationId}/messages.
POST /templates/send sigue devolviendo 200 durante la migracion; POST /template-sends es canonico y devuelve 202.
Tickets sin filtro de atributo, contactos y conversaciones se listan descendentes por actividad; mensajes son cronologicos ascendentes; templates, ascendentes por almacenamiento. Con un atributo Ticket, sigue el cursor y no dependas del orden del indice de busqueda.
Ticket usa timestamps ISO 8601. Recursos CRM heredados aun exponen epoch milliseconds; normalizarlos requiere una version/migracion.
/templates sin query conserva hasta 200 resultados por compatibilidad. Con limit o cursor aplica el maximo normal de 100 y siempre devuelve pagination.

Errores

Todos los errores usan un envelope estable. Los errores internos nunca exponen secretos ni mensajes de proveedor.

unauthorizedforbidden_scopenot_foundvalidation_errorinvalid_requestinvalid_cursorunsupported_media_typerequest_too_largerate_limitedidempotency_key_mismatchidempotency_key_processingidempotency_outcome_unknowninvalid_template_parameterstemplate_not_sendablewhatsapp_connection_not_readytemplate_not_approvedprovider_send_failedinternal_error

json

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request",
    "details": [
      {
        "field": "attributeOperator",
        "reason": "string attributes only support eq"
      }
    ]
  }
}