Construye sobre Drellia con la API REST.

Autenticación

Todos los endpoints, salvo el de estado, necesitan una clave de API. Envía la clave en la cabecera x-api-key. La API también acepta la misma clave como token bearer en la cabecera Authorization.

curl https://api.drellia.com/v1/agents \
  -H "x-api-key: $DRELLIA_API_KEY"

El equipo de Drellia emite la clave de API de tu organización. Para obtenerla, pídesela a tu gestor de cuenta o escribe a support@drellia.com. Una misma clave sirve para Auditoría y para Voz.

La clave es secreta. Guárdala en tu servidor. No la pongas en una URL, un log, el control de versiones ni en código del navegador. Drellia muestra la clave solo cuando la emite o la rota.

Una petición sin clave, o con una clave no válida, recibe HTTP 401.

URL base

https://api.drellia.com/v1

Envía todas las peticiones por HTTPS al servidor de producción. La ruta de cada endpoint empieza por el prefijo de versión /v1. El endpoint de estado está en /health, sin prefijo y sin clave.

Los cuerpos de petición y respuesta son JSON. Las fechas son cadenas ISO 8601 en UTC. La excepción es originalDateTime, un tiempo Unix en milisegundos que viene de tu propio sistema.

Inicio rápido: audita la transcripción de un chat

Estos pasos envían una conversación a auditoría. Necesitas una clave de API, un empleado que pertenezca a un departamento y un cliente. Créalos en la app o con los endpoints de Employees y Customers.

1. 1

   Comprueba que la API responde

   El endpoint de estado no necesita clave.

   curl Copiar

   curl https://api.drellia.com/health

2. 2

   Busca el proveedor

   Cada conversación llega por un proveedor, por ejemplo tu canal de chat. Copia el id del proveedor.

   curl Copiar

   curl https://api.drellia.com/v1/providers \
     -H "x-api-key: $DRELLIA_API_KEY"

3. 3

   Crea la conversación

   Envía el proveedor, el empleado, el cliente y la hora de la conversación. La respuesta trae el id de la conversación y el estado PENDING.

   curl Copiar

   curl -X POST https://api.drellia.com/v1/conversations \
     -H "x-api-key: $DRELLIA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "providerId": "<provider id>",
       "employeeId": "<employee id>",
       "customerId": "<customer id>",
       "originalDateTime": 1760000000000
     }'

4. 4

   Añade la transcripción

   Envía todos los mensajes en una sola petición. Drellia evalúa la conversación después de esta llamada.

   curl Copiar

   curl -X POST https://api.drellia.com/v1/conversations/<conversation id>/messages \
     -H "x-api-key: $DRELLIA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "messages": [
         { "senderRole": "employee", "content": "Good morning, this is Ana from customer care.", "originalDateTime": 1760000000000 },
         { "senderRole": "customer", "content": "Hello, I want to check my last invoice.", "originalDateTime": 1760000004000 }
       ]
     }'

5. 5

   Consulta el estado

   Cuando el estado es COMPLETED, la evaluación está lista en la app de Drellia.

   curl Copiar

   curl https://api.drellia.com/v1/conversations/<conversation id> \
     -H "x-api-key: $DRELLIA_API_KEY"
   # { "id": "…", "status": "COMPLETED", … }

Sube la grabación de una llamada (JavaScript)

Para una llamada telefónica, sube el audio en lugar de los mensajes. Pide una URL de subida y envía el archivo a esa URL con un HTTP PUT. Drellia transcribe el audio y evalúa la llamada. Una conversación puede tener un archivo de audio.

import { readFile } from 'node:fs/promises';

const BASE_URL = 'https://api.drellia.com';
const headers = {
  'x-api-key': process.env.DRELLIA_API_KEY,
  'Content-Type': 'application/json',
};

// 1. Create the conversation.
const conversation = await fetch(`${BASE_URL}/v1/conversations`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    providerId: '<provider id>',
    employeeId: '<employee id>',
    customerId: '<customer id>',
    originalDateTime: Date.now(),
  }),
}).then((r) => r.json());

// 2. Ask for an upload URL for the recording.
const audio = await readFile('call.mp3');
const { uploadUrl } = await fetch(
  `${BASE_URL}/v1/conversations/${conversation.id}/generate-upload-url`,
  {
    method: 'POST',
    headers,
    body: JSON.stringify({
      fileName: 'call.mp3',
      fileSize: audio.byteLength,
      contentType: 'audio/mpeg',
    }),
  },
).then((r) => r.json());

// 3. Upload the audio. Drellia transcribes and evaluates the call.
await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'audio/mpeg' },
  body: audio,
});

Inicia una llamada con un agente de voz (Python)

Inicia una llamada saliente con uno de tus agentes. El parámetro de ruta del agente acepta el id del agente o su clave corta (AGT-…). Usa el sessionId de la respuesta para encontrar la llamada después.

import os
import requests

BASE_URL = "https://api.drellia.com"
headers = {"x-api-key": os.environ["DRELLIA_API_KEY"]}

response = requests.post(
    f"{BASE_URL}/v1/agents/AGT-A1B2C3/calls",
    headers=headers,
    json={"phoneNumber": "+15555550100"},
    timeout=30,
)
response.raise_for_status()
call = response.json()
print(call["sessionId"], call["status"])

Convenciones

Los endpoints de listado aceptan los parámetros de consulta page y pageSize. La primera página es la 1. El tamaño de página por defecto es 50 y el máximo es 1000. Una respuesta de listado tiene la forma { results, total, page, pageSize }.

Cada recurso tiene un id, que es un UUID. Algunos recursos también tienen una entityKey corta, por ejemplo AGT-A1B2C3. Cuando una ruta acepta una entityKey, la referencia lo indica.

Una respuesta de error de la API tiene un estado HTTP de 400 o superior y un cuerpo JSON con statusCode, message y error. En un error de validación (HTTP 400), message es una lista con una línea por cada campo no válido. La API rechaza un cuerpo con un campo que no conoce. Un borrado correcto devuelve HTTP 204 sin cuerpo. La respuesta de límite de peticiones (HTTP 403) viene del borde de la red y no tiene este cuerpo.

{
  "statusCode": 404,
  "message": "Conversation with ID 3f2b9c1e-8a4d-4f6b-9c2e-1d7a5b8e0f42 not found",
  "error": "Not Found"
}

La API acepta hasta 2000 peticiones en cada ventana de 5 minutos desde una misma dirección IP. Por encima de eso, devuelve HTTP 403 hasta que termina la ventana. Contacta con soporte si necesitas un límite mayor.

Recursos

• Referencia de la API open_in_new Cada endpoint, parámetro y respuesta, con la opción de probar peticiones con tu clave. La sirve la propia API, siempre actualizada.
• Contrato OpenAPI 3 (JSON) El contrato OpenAPI 3, para generar un cliente o importarlo en tu herramienta de APIs.
• Soporte para desarrolladores ¿Dudas sobre el acceso a la API o una integración? Escribe a support@drellia.com.