Custom API and your own backend

What it is

"Custom API" is not a plugin you download. It is the catch-all name for connecting Agentency to something we do not have a ready-made card for — your own back office, an internal booking system, a stock database, or a tool nobody else uses.

There are only two directions, and picking the right one is most of the work:

• Agentency calls you. During a conversation the chatbot reaches out to an address you control and uses the answer in its reply. This is a Call action.
• You call Agentency. Your own server or script asks Agentency to do something — list your chatbots, add knowledge, send a message. This uses a personal access token.

Most "can it look up an order?" questions are the first direction. Most "can I add products from my system every night?" questions are the second.

When you would use it

Choose a Call action when the answer has to be live and specific to the person asking: an order status, a booking slot, whether a course still has places.

Choose a personal access token when your systems should drive Agentency: a nightly job that pushes an updated price list into knowledge, a script that creates a chatbot for each new client, or a back-office screen that shows recent conversations.

If you use Zapier or Make as the middle layer, read Zapier and Make — the same mechanism, with the automation platform doing the plumbing.

Where to find it

Open Dashboard → Chatbots → your chatbot → Actions for Call actions, and Dashboard → Settings → Developer for keys.

Steps

Direction one — the chatbot calls your system:

1. Have your developer expose one address that answers the question, and nothing more. A single endpoint that takes an order number and returns a status is a much safer thing to expose than a general-purpose API.
2. In Agentency, open the Actions tab and create an HTTP action pointing at it.
3. Describe clearly when the chatbot should use it, and what pieces of information it must collect first.
4. Test in Test Chatbot, then read Call action history to confirm the call and the response.

Direction two — your system calls Agentency:

1. Open Dashboard → Settings → Developer (owner only) and create a personal access token.
2. Give it the smallest set of scopes that does the job. A key that lives on someone else's server should never carry more than it needs.
3. Copy the key — it is shown once.
4. Send it as a bearer token to the API host. There is no /api prefix; see API host — no /api prefix.
5. Start with one read request, confirm it works, then build.
6. If a key is ever exposed, revoke it. Revoking a key does not sign you out of the dashboard.

What a request looks like

Listing your chatbots, with the key as a bearer token:

curl https://api.agentency.com/chatbots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Note what is not there: no /api in the path, and no cookie. The path starts at the resource on the API host. Adding /api is the single most common mistake and produces a confusing 404 on an address that looks correct.

Your API host is the same address that appears in your widget snippet, so if you are ever unsure, copy it from there:

<script src="https://agentency.com/js/chatbot-widget.js" defer data-widget-token="wt_YOUR_WIDGET_TOKEN" data-api-base-url="https://api.agentency.com" referrerpolicy="strict-origin-when-cross-origin" crossorigin="anonymous"></script>

The address in data-api-base-url is the API origin. The widget token beside it is a public value meant to sit in a web page; it is not an API key and cannot be used in its place.

What you will see

The Actions tab is a table of the tools this chatbot may use, with history showing each attempt and its result.

Settings → Developer is a table of your keys — name, scopes, last used — alongside the API reference. It is not a download page; there is no zip file to install.

Limits and plan notes

Call actions count against a per-chatbot limit that rises with your plan; Free has none. See the pricing page and Which plans include integrations.

Personal access tokens are owner-only. If you are working inside someone else's account as a team member, the Developer page is not shown — that is deliberate, and the same rule that keeps Billing owner-only.

For safety, addresses the chatbot calls must be ordinary public HTTPS addresses. Requests aimed at internal or private network addresses are refused, so an internal-only service needs a small public endpoint in front of it.

Give each integration its own key with its own scopes. A key pasted into a website's admin should have the narrowest scope that works — for embedding, that is the widget scope only, never a broad one. See Choose token scopes.

Common problems

My request 404s on /api/chatbots.

Drop the /api. The path is /chatbots on the API host.

I get HTML back instead of data.

You are calling the dashboard or the marketing site instead of the API host. Use the address from data-api-base-url.

Developer is missing from Settings.

You are not the account owner, or you are acting in another account. Switch back to your own account.

I used the widget token as an API key.

They are different things. The widget token is public and only lets a browser open a chat; API calls need a personal access token.

The chatbot will not call my endpoint.

Check that the action is enabled, that the address is public HTTPS, and that the description states plainly when to use it. Then read Call action history — a call that was attempted and failed is a very different problem from one that never happened.