🔌 Documentation: API

Integration with your CRM/systems. What it is, how it works and how to use it — explained step by step.

Request a quote See service See all modules

🔌 API TelHarbor

Integrate SMS, WhatsApp and Click-to-dial into your systems. Base: https://api.telharbor.com/v1

💬

SMSSend text messages. Scopes: sms.send, sms.status

🟢

WhatsAppSend WhatsApp messages. Scopes: whatsapp.send, whatsapp.status

📞

Click-to-dialOriginate calls on the client PBX. Scope: dial.call

Each API key is enabled by TelHarbor with the contracted service(s). Request your key from the support team.

🤔 What is an API?

API stands for Application Programming Interface. In plain words: it is a doorway that lets your system (your CRM, website or app) ask TelHarbor to do things automatically, without a person doing it by hand.

🧑‍💻You (your system)Wants to send an SMS or make a call

→

🧑‍🍳The API (the waiter)Takes your order and brings the answer

→

🏢TelHarbor (the kitchen)Does the work: sends, calls, logs

It is like a waiter in a restaurant: you do not go into the kitchen; you ask the waiter and they bring what you need. The API is that middleman: you ask (a request) and get a response.

The conversation: request and response

This works the same for all TelHarbor services: SMS, WhatsApp and Click-to-dial. What you ask and receive changes, but the mechanism (ask with your key → get a response) is the same.

🗺️ How does the TelHarbor API work?

Your system connects only to the TelHarbor API (never directly to the phone network or the PBX). TelHarbor validates your key, applies the security limits and runs the action on the right service.

Security: your system never connects directly to the phone system or the providers. Everything goes through the TelHarbor API, which validates and logs every request.

📞 Click-to-dial flow (step by step)

With a single request, TelHarbor first rings the agent's extension and, when they answer, dials the destination. The agent never types the number: they answer their phone and are already calling.

Call center security: you can hide the customer number on the agent screen (they will only see the name assigned to the key). The destination sees the CallerID of your PBX outbound route, not your system.

🔑 Authentication, limits & security

Authenticate every request with your API key in a header:

X-API-Key: <YOUR_API_KEY> # or: Authorization: Bearer <YOUR_API_KEY>

IP allowlist: optionally your key is restricted to authorized IPs/CIDR.
Rate limit per minute and daily quota per key.
Every call is stored in the usage log (audit & billing).
Scopes: the key can only use the services assigned to it.

Test connection GET /ping

curl -H "X-API-Key: <YOUR_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: <YOUR_API_KEY>" -H "Content-Type: application/json" \ -d '{"from":"<YOUR_NUMBER>","to":"+50688887777","text":"Hola desde TelHarbor"}'

🟢 WhatsApp POST /whatsapp/send

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

Message status GET /messages?id=123

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

📞 Click-to-dial POST /dial/call

Rings the agent extension and, upon answer, dials the destination. The client never connects directly to the PBX: TelHarbor originates it securely via AMI.

Request

Field	Required	Description
`from`	Yes	Agent extension on your PBX (e.g. `2072`). It rings first.
`to`	Yes	Destination number (E.164, e.g. `+50688887777`) or an internal extension.
`caller_id`	No	CallerID to show. If omitted, the name configured on the key applies.

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

Response

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

The PBX to use is associated with your API key by TelHarbor; it is not sent in the request. A key can only originate on its assigned PBX.

⚠️ Errors

Error responses with ok:false and the matching HTTP status:

HTTP	Meaning
`401`	Missing or invalid API key.
`403`	Missing required scope, IP not allowed, or resource not owned.
`400`	Invalid parameters (e.g. `from`/`to`).
`429`	Rate limit or daily quota exceeded.
`502`	Provider / AMI failure while processing.