🔌 Documentación: API

Name: TelHarbor
Address: San Antonio de Coronado, Coronado, San José, 840-2200, CR
Telephone: +50643000000
Price range: $$

Integración con su CRM/sistemas. Qué es, cómo funciona y cómo se usa — explicado paso a paso.

Solicitar cotización Ver servicio Ver todos los módulos

🔌 API TelHarbor

Integre SMS, WhatsApp, Click-to-dial, datos de llamadas y webhooks (screen-pop) en sus sistemas. Base: https://api.telharbor.com/v1

💬

SMSEnviar mensajes de texto. Scopes: sms.send, sms.status

🟢

WhatsAppEnviar mensajes por WhatsApp. Scopes: whatsapp.send, whatsapp.status

📞

Click-to-dialOriginar llamadas en la PBX del cliente. Scope: dial.call

Cada API key la habilita TelHarbor con el/los servicios contratados. Solicite su key al equipo de soporte.

🤔 ¿Qué es un API?

API significa Application Programming Interface (Interfaz de Programación de Aplicaciones). En palabras simples: es una puerta de entrada que permite que su sistema (su CRM, su sitio web, su aplicación) le pida cosas a TelHarbor de forma automática, sin que una persona tenga que hacerlo a mano.

🧑‍💻Usted (su sistema)Quiere enviar un SMS o hacer una llamada

→

🧑‍🍳El API (el mesero)Lleva su pedido y le trae la respuesta

→

🏢TelHarbor (la cocina)Hace el trabajo: envía, llama, registra

Es como un mesero en un restaurante: usted no entra a la cocina; le pide al mesero y él le trae lo que necesita. El API es ese intermediario: usted pide (una solicitud) y recibe una respuesta.

La conversación: solicitud y respuesta

Esto aplica igual para todos los servicios de TelHarbor: SMS, WhatsApp y Click-to-dial. Cambia lo que usted pide y lo que recibe, pero el mecanismo (pedir con su llave → recibir respuesta) es el mismo.

🗺️ ¿Cómo funciona el API de TelHarbor?

Su sistema se conecta solo al API de TelHarbor (nunca directo a la red telefónica ni a la central). TelHarbor valida su llave, aplica los límites de seguridad y ejecuta la acción en el servicio correcto.

Seguridad: su sistema nunca se conecta directo a la central telefónica ni a los proveedores. Todo pasa por el API de TelHarbor, que valida y registra cada solicitud.

📞 Flujo del Click-to-dial (paso a paso)

Con una sola solicitud, TelHarbor primero timbra la extensión del agente y, cuando contesta, marca al destino. El agente nunca digita el número: contesta su teléfono y ya está llamando.

Seguridad para call centers: puede ocultar el número del cliente en la pantalla del agente (solo verá el nombre asignado a la llave). El destino ve el CallerID de la ruta saliente de su PBX, no la de su sistema.

🔑 Autenticación, límites y seguridad

Autentique cada petición con su API key en un header:

X-API-Key: <SU_API_KEY> # o bien: Authorization: Bearer <SU_API_KEY>

IP allowlist: opcionalmente su key se restringe a IPs/CIDR autorizados.
Rate limit por minuto y cuota diaria por key.
Todas las llamadas quedan en el registro de uso (auditoría y facturación).
Scopes: la key solo puede usar los servicios que tenga asignados.

Probar conexión GET /ping

curl -H "X-API-Key: <SU_API_KEY>" https://api.telharbor.com/v1/ping

💬 SMS POST /sms/send

curl -X POST https://api.telharbor.com/v1/sms/send \ -H "X-API-Key: <SU_API_KEY>" -H "Content-Type: application/json" \ -d '{"from":"<SU_NUMERO>","to":"+50643000000","text":"Hola desde TelHarbor"}'

🟢 WhatsApp POST /whatsapp/send

curl -X POST https://api.telharbor.com/v1/whatsapp/send \ -H "X-API-Key: <SU_API_KEY>" -H "Content-Type: application/json" \ -d '{"from":"<SU_NUMERO>","to":"+50643000000","text":"Hola desde TelHarbor"}'

Fuera de la ventana de 24 horas WhatsApp solo entrega plantillas aprobadas. Envíe template con el nombre, el idioma y una variable por cada {{n}}; text pasa a ser opcional.

Estado de un mensaje GET /messages?id=123

curl -H "X-API-Key: <SU_API_KEY>" "https://api.telharbor.com/v1/messages?id=123"

📞 Click-to-dial POST /dial/call

Timbra la extensión del agente y, al contestar, marca al destino. El cliente nunca se conecta directo a la PBX: TelHarbor la origina de forma segura vía AMI.

Petición

Campo	Requerido	Descripción
`from`	Sí	Extensión del agente en su PBX (ej. `7631`). Es la que suena primero.
`to`	Sí	Número destino (E.164, ej. `+50643000000`) o una extensión interna.
`caller_id`	No	CallerID a mostrar. Si se omite, aplica el nombre configurado en la llave.

curl -X POST https://api.telharbor.com/v1/dial/call \ -H "X-API-Key: <SU_API_KEY>" -H "Content-Type: application/json" \ -d '{"from":"7631","to":"+50643000000"}'

Respuesta

{"ok":true,"message":"Call originated","call":{"from":"7631","to":"+50643000000","action_id":"thapi_req_..."},"request_id":"req_..."}

La PBX a usar queda asociada a su API key por TelHarbor; no se envía en la petición. Una key solo puede originar en su PBX asignada.

📇 Datos: llamadas, colas y grabaciones

Endpoints de solo lectura. Cada API key ve únicamente los recursos de su alcance (las extensiones y la cola que TelHarbor le asigna); pedir otro recurso responde 403/404.

Registros de llamadas (CDR) GET /v1/calls

Lista de llamadas por rango de fechas. Una llamada puede aparecer en varias filas con el mismo call_id (el linkedid), que se usa para pedir su grabación.

curl "https://api.telharbor.com/v1/calls?date_from=2026-09-01&limit=50" \ -H "X-API-Key: <SU_API_KEY>"

Parámetros: date_from, date_to (YYYY-MM-DD[ HH:MM:SS]), extension, limit (máx 200), offset. Scope: calls.read.

Estado de la cola GET /v1/queues/status?queue=NNNN

Foto instantánea de la cola: llamadas en espera, nivel de servicio y agentes con su estado y pausa.

curl "https://api.telharbor.com/v1/queues/status?queue=7632" \ -H "X-API-Key: <SU_API_KEY>"

Devuelve waiting, agents_available, service_level_pct y agents[]. Scope: queues.read.

Grabaciones GET /v1/recordings/get?call_id=<linkedid>

Descarga (stream) el audio de una llamada de su alcance. Devuelve audio/wav con soporte de HTTP Range; el audio no se almacena de nuestro lado. Un call_id ajeno responde 404.

curl "https://api.telharbor.com/v1/recordings/get?call_id=call_EJEMPLO…" \ -H "X-API-Key: <SU_API_KEY>" --output llamada.wav

Scope: recordings.read.

🔔 Webhooks — eventos en tiempo real (screen-pop)

En vez de que usted consulte a cada rato, TelHarbor le avisa: por cada evento de sus llamadas le hacemos un POST a una URL suya. Ideal para el screen-pop (abrir la ficha del cliente cuando entra la llamada) y para mantener el tablero al día.

Cómo se activa

Usted nos indica una URL https pública (con certificado válido) que reciba POST.
TelHarbor la registra y le entrega un secreto (whsec_…) para verificar la firma.
A partir de ahí recibe los eventos de sus llamadas, en tiempo casi real.

Eventos

Evento	Cuándo
`call.queued`	La llamada entró a la cola.
`call.ringing`	Timbra en el agente → abrir la ficha (screen-pop).
`call.answered`	El agente contestó.
`call.completed`	Terminó (trae duración).
`call.missed`	Abandonada / no contestada.

También existen message.inbound y message.status (SMS/WhatsApp/Email) para quienes usan mensajería.

Ejemplo de evento

POST (a su URL)Content-Type: application/json X-TH-Signature: t=1789340576,v1=EJEMPLO… {"id":"evt_5f01...","type":"call.ringing","api_version":"v1", "created_at":"2026-09-13T23:02:53Z", "data":{"call_id":"call_EJEMPLO…","queue":"7632","direction":"inbound", "agent_extension":"7633","caller_number":"+50643000000","did":"+18887317044", "wait_seconds":0,"event_at":"2026-09-13T23:02:53Z"}}

Verificar la firma (HMAC) — obligatorio

La cabecera es X-TH-Signature: t=<unix>,v1=<hmac>. Recalcule HMAC-SHA256(secreto, "<t>.<cuerpo_crudo>") y compárelo con v1. Rechace si no coincide o si t tiene más de ~5 min (anti-repetición). Use el cuerpo crudo, sin re-serializar.

// PHP$raw = file_get_contents('php://input'); preg_match('/t=(\d+),v1=([a-f0-9]+)/', $_SERVER['HTTP_X_TH_SIGNATURE'] ?? '', $m); $mine = hash_hmac('sha256', $m[1] . '.' . $raw, $SECRET); if (!hash_equals($mine, $m[2] ?? '') || time() - (int)$m[1] > 300) { http_response_code(400); exit; } $evt = json_decode($raw, true); // $evt['type'], $evt['data']http_response_code(200); // responder rápido; procesar aparte

Cómo probar

Para una prueba sin escribir código, apunte el webhook a un capturador temporal (p.ej. un bin de webhook.site) y pídanos activarlo.
Haga una llamada de prueba a su cola: verá llegar los POST firmados (call.ringing, answered, completed).
Verifique la firma con su secreto antes de procesar; responda 2xx de inmediato (si falla, reintentamos con espera creciente).

Solo recibe eventos de su cola y agentes. Use el id del evento (evt_…) para no procesar dos veces un reintento (idempotencia).

📅 Calendario de reservas

Publique sus horarios libres y reciba reservas en su propio sitio. Cada reserva crea el contacto y la cita en CRM → Calendario, con enlace de videollamada, correo de confirmación y recordatorio. Scopes calendar.slots, calendar.book y calendar.manage. El horario de atención, la duración y quién atiende los configura TelHarbor.

Horarios libres GET /v1/calendar/slots

curl https://api.telharbor.com/v1/calendar/slots -H "Authorization: Bearer <API_KEY>"

Reservar POST /v1/calendar/book

curl -X POST https://api.telharbor.com/v1/calendar/book -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \ -d '{"start":"2026-09-16T10:00:00-06:00","name":"Ana","email":"ana@empresa-demo.example","company":"Empresa","modality":"video","lang":"es","tz":"America/Costa_Rica","manage_url":"https://su-sitio.example/reserva/?t={token}"}'

Responde token (guárdelo: da acceso a la reserva) y meet_url. Si el horario ya se tomó responde 409 con slot_unavailable. Para cambiar de horario envíe replace_token con el token anterior.

Consultar y cancelar GET /v1/calendar/booking?token=… POST /v1/calendar/cancel

⚠️ Errores

Respuestas de error con ok:false y HTTP correspondiente:

HTTP	Significado
`401`	API key ausente o inválida.
`403`	Sin el scope requerido, IP no permitida, o recurso no propio.
`400`	Parámetros inválidos (ej. `from`/`to`).
`429`	Rate limit o cuota diaria excedida.
`502`	Fallo del proveedor / AMI al procesar.

🎬 Video: recorrido por su API

Unos dos minutos: cómo entrar con seguridad, sus llaves y sus límites, el registro de uso, solicitar números y cómo conectarse con la documentación. Tiene narración: active el sonido.

Datos de ejemplo con llaves, direcciones y números ficticios. Debajo, las mismas pantallas explicadas punto por punto.

🧭 Su API en el portal

En el menú CPaaS → API's consulta sus llaves, el registro de cada llamada que hace su sistema y solicita números. La creación y los cambios de llaves los hace el equipo de TelHarbor. Los eventos que TelHarbor le envía están en Webhooks.

🔑 Mis llaves de API

Las llaves con las que su sistema se conecta, y qué puede hacer cada una.

Datos de ejemplo: llaves, direcciones IP y números ficticios; las llaves reales nunca se muestran completas. Toque la imagen para verla en tamaño completo.

1
Solo lectura
Las llaves se consultan aquí; crearlas o cambiarlas lo hace el equipo de TelHarbor.
2
Nombre
Para qué sistema es la llave.
3
Prefijo
Solo el inicio de la llave, para reconocerla. La llave completa se entrega una sola vez y no se vuelve a mostrar.
4
Permisos
Qué puede hacer: enviar SMS o WhatsApp, consultar estados, agendar, llamar…
5
Estado
Activa o deshabilitada.
6
Límites
Cuántas llamadas por minuto y por día admite.
7
Último uso
Cuándo la usó su sistema por última vez.
8
Llave deshabilitada
Ya no funciona; si su sistema la sigue usando, recibirá un error.

📊 Registros de uso

Cada llamada que hizo su sistema al API, para revisar qué pasó.

Datos de ejemplo: llaves, direcciones IP y números ficticios; las llaves reales nunca se muestran completas. Toque la imagen para verla en tamaño completo.

1
Llamadas hoy
Cuántas llamadas hizo su sistema hoy.
2
Correctas
Las que respondieron bien (2xx y 3xx).
3
Errores
Las que fallaron (4xx y 5xx): revise la fila para ver cuál.
4
Endpoint
A qué servicio llamó, por ejemplo /v1/sms/send.
5
Método
GET para consultar, POST para enviar.
6
Permiso
El permiso de la llave que se usó.
7
Código HTTP
La respuesta: 200 es correcta; 400 suele ser un dato mal enviado; 401 o 403, una llave o permiso inválido.
8
IP
Desde qué dirección llamó su sistema; útil si su llave solo acepta ciertas direcciones.
9
Una fila con error
Un ejemplo de llamada rechazada, para ubicarla por fecha y endpoint.

📱 Solicitar un número

Pida números para usar con el API; el equipo de TelHarbor los revisa y los activa.

Datos de ejemplo: llaves, direcciones IP y números ficticios; las llaves reales nunca se muestran completas. Toque la imagen para verla en tamaño completo.

1
País
El país y su código.
2
Tipo
Para voz, SMS, WhatsApp o mixto.
3
Cantidad
Cuántos necesita.
4
Enviar solicitud
La envía al equipo de TelHarbor; no se compra automáticamente.
5
Notas
Para qué lo va a usar o qué prefijo prefiere.
6
Estado
Pendiente, aprobada o ya asignada.
7
Nota del equipo
Lo que le respondió TelHarbor, por ejemplo el número asignado.
8
Quién administra
Las llaves y el alta de números los controla y autoriza TelHarbor.