The EchoHub API Guide 2026: Connecting Voice and Chat Agents to Your Software via REST API

In short: The EchoHub API is EchoCall's REST interface at https://hub.echocall.de/api/v1. It lets your own software create voice and chat agents, read conversations and analytics, buy phone numbers and receive events through signed webhooks. You authenticate with an API key sent as a bearer token, which you generate in the Developer area of the EchoHub. The full reference is public, including an OpenAPI file. [1][2]

We rewrote this post in October 2026. The old version promised ready-made connections to ERP systems and phone systems as well as real-time sentiment analysis. We could not find any of that in the API reference, so it has gone. Every endpoint and field in this text appears in the published reference, version 1.13.0. [2]

What the EchoHub API is

The EchoHub is the interface in which EchoCall customers build their agents. The API offers the same building blocks to programs instead of people. It follows REST, speaks JSON and is described as an OpenAPI 3.1 file. Any common generator turns that file into a client for your language, and Postman or Insomnia can import it.

A first test needs no key:

curl https://hub.echocall.de/api/v1/health

The response contains the status and the running version. On 6 October 2026 that was "version":"1.13.0". [3]

When you need the API, and when you do not

Many connections need no code. Google Calendar, Outlook, HubSpot, Salesforce, Zendesk and other services are connected in the EchoHub as integrations. The agent then uses them as tools during a conversation: it books an appointment, looks up a contact or creates a ticket. For your own systems without a ready-made integration there are custom webhooks as tools. The post How to Build an AI Agent Without Code shows how that works.

The API is worth it in three cases:

1. You build EchoCall into your own product. A practice management system, a shop back end or an intranet should create agents and show conversations without your users ever opening the EchoHub.
2. You process events automatically. After every chat a record should land in your data warehouse, or a new ticket should appear in your help desk.
3. You sell agents to your own customers. Agencies, hosting providers and MSPs create customer accounts, distribute credit and handle billing. EchoCall's WHMCS module and white label portal use exactly these endpoints.

The EchoCall API endpoints at a glance

In version 1.13.0 the reference covers exactly 130 paths. [2] The most important groups:

On top of that come tickets, integrations, voices, languages, notifications and campaigns for call lists under /batch-calling/campaigns.

Creating an API key: authentication and scopes

You generate the key in the Developer area of the EchoHub at hub.echocall.de/developer. You give it a name and can set two restrictions: a list of allowed IP addresses and a list of allowed domains, checked against the Origin and Referer headers. Requests from anywhere else are rejected with status 403. The full key is shown only once, right after you create it. In the same area you can revoke keys and look through the request logs of your keys.

The key starts with eck_live_, followed by 64 hexadecimal characters, and goes into every request as a bearer token:

curl -H "Authorization: Bearer $ECHOCALL_API_KEY" "https://hub.echocall.de/api/v1/agents?page=1&perPage=20"

Three points that save trouble in practice:

• There is no test mode. Every key works on your real account. Buying a number through the API costs real credit. Use a separate key for experiments and stick to read-only endpoints until your code is ready.
• The key belongs on the server. Never in browser JavaScript, never in an app, never in a Git repository. Whoever holds it acts in your name.
• Every operation requires a scope. The reference names it for each endpoint, for example read:agents or write:webhooks. Keys from the Developer area receive all scopes. If one is missing, the API answers 403 insufficient_permissions and names the scope it needs. The partner endpoints under /resellers and /provisioning also require a reseller account.

First requests: create an agent, add knowledge, test it

A voice agent has two required fields: name and language as an ISO 639-1 language code. Everything else has defaults. Put the content into a file called agent.json:

{
  "name": "Reception Example Practice",
  "language": "en",
  "firstMessage": "Hello, you are speaking to the AI assistant of Example Practice. How can I help?",
  "systemPrompt": "You take appointment requests and answer questions about opening hours and directions.",
  "saveCallAudio": false,
  "retentionDays": 30
}

curl -X POST https://hub.echocall.de/api/v1/agents -H "Authorization: Bearer $ECHOCALL_API_KEY" -H "Content-Type: application/json" -d @agent.json

The response contains the id of the new agent, its name, language, status and creation time. Note the first message: it names the business and says that an AI is speaking. For phone agents you write this notice into the greeting yourself. Why that has been mandatory since August 2026 is explained in the post on the EU AI Act and the AI disclosure duty.

Next, the agent gets its knowledge. The simplest way is a page of your website:

curl -X POST https://hub.echocall.de/api/v1/agents/AGENT_ID/knowledge -H "Authorization: Bearer $ECHOCALL_API_KEY" -H "Content-Type: application/json" -d '{"type":"url","url":"https://www.example.com/services"}'

If the page changes, re-read the source via /agents/{agentId}/knowledge/{knowledgeId}/refresh.

You do not need to buy a number to test. POST /agents/{agentId}/preview opens a test call in the browser. The response returns a WebSocket path on the API host, a maximum duration and a window in which the path may be opened once. [2] That lets your users hear the agent in your own interface before it takes real calls.

Chat agents are created with POST /chatbots. Only the name is required. Besides the id, the response contains a public address for the chat. The agent goes onto your website with one line:

<script src="https://cdn.echocall.de/widget.js" data-id="CHATBOT_ID" async></script>

Webhooks: receiving events and verifying signatures

Instead of polling, let EchoCall notify you. You register an HTTPS address and choose the events:

curl -X POST https://hub.echocall.de/api/v1/webhooks -H "Authorization: Bearer $ECHOCALL_API_KEY" -H "Content-Type: application/json" -d '{"url":"https://api.example.com/echocall/events","events":["conversation.closed","ticket.created"]}'

The response contains a secret. Store it immediately, the API never returns it again. [2] These events are in the catalogue returned by GET /webhooks/events:

"*" subscribes you to all events. Every delivery is a POST with the fields id, event, createdAt and data, plus the header X-EchoCall-Signature in the format t=<unix time>,v1=<hex>. The value v1 is an HMAC-SHA256 over t, a full stop and the raw request body, computed with your secret. [2][4]

Verify every delivery before you trust it. An example in Python:

import hashlib
import hmac
import time


def verify(secret, header, raw_body, tolerance=300):
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts = int(parts.get("t", "0"))
    now = int(time.time())
    if ts + tolerance < now or ts > now + tolerance:
        return False
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Three rules go with it. Compute over the raw body before a framework reshapes the JSON. Compare in constant time, as hmac.compare_digest does. [5] And discard deliveries with a timestamp that is too old, so nobody can replay an intercepted message later. The reference shows the same check in Node.js. [1]

On delivery itself: your endpoint must answer with a 2xx status within 10 seconds. Otherwise EchoCall retries after 1, 5 and 30 seconds. After 25 consecutive failures the endpoint is switched off and receives nothing until you re-enable it with PATCH /webhooks/{id}. POST /webhooks/{id}/test sends a single probe at any time, with no retry. [2]

Three design rules follow from this. Accept deliveries at once and process them afterwards in a queue. Remember the id of every event, because a retry carries the same id and must not be booked twice. And reconcile at fixed intervals via GET /conversations. An event can get lost, for instance while your server restarts, and reconciliation catches that.

Error codes, rate limits and pagination

Every error arrives in the same envelope:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": {}
  }
}

Branch in your code on code, not on the text in message. The texts may change, the codes are the interface. [2]

The rate limit applies per key and per second, 500 requests by default. Every response carries the headers X-RateLimit-Limit and X-RateLimit-Remaining. Anyone above the limit receives 429 with Retry-After: 1. Creating new customer accounts via /provisioning/create is stricter: at most 10 per minute and key. [2]

Lists are paginated. page starts at 1, perPage goes up to 100. The response contains a pagination object. Keep reading until a page returns fewer entries than you asked for.

A voice API with a GDPR contract: data protection via the API

Anyone using a voice API for customer conversations processes personal data on behalf of others. Art. 28 GDPR requires a contract with the processor for that. [6] EchoCall provides its data processing agreement on the DPA page, and its servers are in IONOS data centres in Frankfurt and Karlsruhe. More on the data protection page.

The settings you choose per agent matter more than the paperwork. The API offers three fields for them: [2]

• saveCallAudio decides whether the audio recording is stored. The default is false.
• retentionDays sets how long conversations are kept. The default is 30 days, -1 means permanently.
• zeroPiiRetention switches on Zero-PII mode, for sectors where no personal conversation data should remain stored.

Set these fields deliberately instead of relying on defaults. And note in your record of processing activities which events your webhook receiver stores. What it stores is your responsibility, no longer EchoCall's.

The API for resellers and white label

Agencies and hosting providers that sell agents under their own brand need a reseller account. Two further groups then become available.

Managing customers. POST /resellers/customers creates a customer account, and only the email address is required. Further endpoints distribute credit, assign phone numbers, suspend and unsuspend customers and return invoices as PDF.

Acting on behalf of a customer. With the header X-EchoCall-Customer: <customerId> the same calls, such as GET /agents or POST /chatbots, work on that customer's account. While the header is set, the reseller endpoints are locked. That stops a bug in your customer view from changing partner data.

Connecting billing systems. /provisioning maps the life cycle of a product: create, suspend, unsuspend, terminate, change package. The WHMCS plugin for AI voice and chat agents uses exactly these endpoints. If you want your own customer portal without building it, the open source white label portal is a finished interface on the same API. Partner terms are on the PartnerNet page.

Checklist before going live

1. The key lives only on the server, ideally with an IP restriction.
2. Each integration has its own key, so you can revoke one on its own.
3. Errors are handled by code, and 429 and 5xx are retried with a pause.
4. The webhook receiver checks the signature and time window and spots duplicates by their id.
5. Regular reconciliation via GET /conversations catches lost events.
6. Audio, retention and Zero-PII are set deliberately for each agent.
7. The first message of every phone agent contains the AI notice.

Frequently asked questions

Where can I find the EchoCall API documentation?

The interactive reference is at hub.echocall.de/api/v1/docs, the machine-readable OpenAPI file at hub.echocall.de/api/v1/docs/openapi.json. Both are available without signing in. The reference describes every endpoint with its fields, examples, error codes and the scope it needs.

Is there a sandbox or test mode?

No. Every API key works on your real account, and paid actions such as buying a number are charged to your balance. Test with read-only endpoints and with POST /agents/{agentId}/preview, which opens a test call in the browser without needing a number.

How do I authenticate with the API?

With a key from the Developer area of the EchoHub, sent as Authorization: Bearer eck_live_.... The API accepts no other form. Optionally you can tie the key to specific IP addresses or domains.

Which webhook events are there?

Ended phone calls, incoming and outgoing chat messages, closed conversations and new or updated tickets. Every delivery is signed with HMAC-SHA256, and failed deliveries are retried after 1, 5 and 30 seconds.

Can I manage customer accounts via the API as an agency?

Yes, with a reseller account. You create customers, distribute credit, assign phone numbers and act on behalf of a customer through the X-EchoCall-Customer header. For billing systems there are the provisioning endpoints, which the WHMCS module also uses.

Is there an official SDK?

Not at the moment. From the OpenAPI file you can generate a typed client for your language with a common generator. Often a lean HTTP client is enough, as all requests follow the same pattern.

Sources

1. EchoCall API Reference, interactive documentation: hub.echocall.de/api/v1/docs
2. EchoCall OpenAPI specification, version 1.13.0: hub.echocall.de/api/v1/docs/openapi.json
3. EchoCall API, health endpoint with version: hub.echocall.de/api/v1/health
4. RFC 2104, HMAC: Keyed-Hashing for Message Authentication: rfc-editor.org
5. Python documentation, hmac module with compare_digest: docs.python.org
6. Regulation (EU) 2016/679 (GDPR), Art. 28 Processor: eur-lex.europa.eu

All links were checked on 6 October 2026. This post is not legal advice.

Read next

• WHMCS Plugin: Sell AI Voice & Chat Agents as a Hosting Add-On
• White Label AI Agent Platform 2026: the open source portal
• AI chatbot on WordPress with the EchoCall plugin
• AI and Data Security 2026: The Comprehensive GDPR Guide for Voice Agents