Skip to content
Developers
Channels & integrations

API channel

Connect Entagl to your own app or to Make: send messages in, get replies back, and manage your workspace.

Overview

The API channel lets you run the same AI agent that powers your DMs from your own website chat, mobile app or backend. You send a message, the agent thinks (with the same buffering and human-like, multi-message replies as a real DM), and the reply reaches you a little later, through a webhook callback or by polling. Set it up under Channels → API: generate an API key, turn the channel on, then choose callback or polling. The same API also lets your developer, or Make, work with contacts, conversations, bookings, orders and more. See the Workspace API tab.

For developers: API reference
Every endpoint, field and webhook event, with code samples.

Tabs on this page

The API isn't only for chat. Your developer, or a tool like Make, can use it to read and update most of your workspace.

What you can do with it

Besides sending messages, the API covers:

  • Contacts: create, update, look up, merge, add notes, mark as do-not-contact
  • Tags and lifecycle stages: add or remove tags, move a contact to another stage
  • Conversations: assign to a teammate, close with a closing note, pause or resume the AI, add team comments, send a message as your business
  • Bookings and reminders: check free times, book, reschedule, cancel, create and close reminders
  • Orders and products: create and update orders and their items, manage your catalog
  • Calls: start an AI phone call or queue one, read the result
  • Campaigns: see your campaigns and send one

When something changes, Entagl can tell your tools right away through webhooks.

Two ways to sign in

Make. When you connect Make, you sign in with your own Entagl account. Make then acts as you, with exactly your rights: an owner or admin can do everything, a team member only what their privileges allow. If your login has more than one workspace, you choose which one to use.

API key. For your own server, create a key under Channels → API or Settings → API keys and send it as Authorization: Bearer <your key>. A key belongs to one workspace and has full owner access to it, so treat it like a password.

Safe to retry: the Idempotency-Key header

Sometimes a request goes through but the answer gets lost on the way back. If your system isn't sure a request worked, it can send it again with the same Idempotency-Key header. Within 24 hours Entagl recognizes the key, skips the work and returns the first answer, so you don't end up with two orders or two contacts. Using the same key for a different request is refused with an error.

How many requests you can send

Up to 120 requests per minute for each workspace. Go over that and Entagl answers with error 429 (rate_limited). Wait a moment and try again. Most automations never get close.

The full API reference

Every endpoint, field and error code is listed in the Entagl API reference. If your developer doesn't have it yet, email support@entagl.com and ask for the API reference.

An API key gives full owner access to its workspace. Keep it on your server, never inside a website or app your customers can open, and revoke it as soon as you think it leaked.
Changes made through the API are marked as coming from the API in your webhook events, so a Make scenario can ignore its own changes instead of looping.

Features

Set up & authenticate

Generate an API key under Channels → API, enable the channel toggle, then call the API at https://api.entagl.com with the header Authorization: Bearer <your key>. Keys are workspace-scoped.

Send a message

POST /api/v1/messages with { message, externalUserId }. You get a 202 and a conversationId right away. Reuse that conversationId to continue the conversation. The agent's reply arrives later, not in this response.

Webhook callback (recommended)

Add a public HTTPS callback URL and Entagl POSTs each agent reply to it, signed with the X-Entagl-Signature header (HMAC-SHA256). Verify the signature and respond 2xx within about 5 seconds. There is no automatic retry.

Polling

If you can't host a callback URL, call GET /api/v1/conversations/:id/messages?since=<cursor> to fetch new replies. Pass the cursor from each response back as ?since= so you only receive new messages.

Security & isolation

API keys are stored hashed and the signing secret is encrypted (both shown only once). Every lookup is workspace-scoped: a conversation ID from another workspace returns 404, and you can't pass a user ID (it's derived from your key).

Common tasks

Set up the API channel

About 3 min
  1. Go to Channels → API and click Generate API Key. Copy it now, because it's shown only once.
  2. Turn on the channel toggle in the API card header.
  3. Recommended: expand the card, paste a public HTTPS callback URL, save, and copy the signing secret.
  4. From your app, POST messages to https://api.entagl.com/api/v1/messages and receive replies via your callback or by polling.

Tips

Replies are asynchronous. The POST returns 202, and the agent's reply arrives via your callback or polling, not in the response.
One message can produce several replies after a short buffering delay (about 8 seconds, configurable up to ~5 minutes). Render them all, in order.
A 202 doesn't guarantee a reply. The agent may stay silent if automation is paused, a guardrail blocks the message, or the workspace is out of credits.
Callbacks have no automatic retry. Keep polling as a backup, and always verify the X-Entagl-Signature header before trusting a delivery.
Reuse the conversationId to continue a conversation; externalUserId is just your own label for the end-user.
Text only for now. Keep your API key and signing secret safe: both are shown only once.

Frequently asked questions

Was this page helpful?