Catch Hook & API

How Catch Hook works#

Add a Catch Hook step to a chatbot in Chat Builder. When your system calls the Agentim API with that step's name and a customer's phone number, Agentim messages the customer on WhatsApp. Any data you send becomes variables for that conversation.

A Catch Hook step has two trigger types:

• Start Message starts the flow at the step connected to the hook, so the customer can reply and continue.
• Pop Up sends one standalone message (the step's text).

Not sure whether you need Catch Hook or the HTTP step? The difference is who makes the call:

Get your API key#

1. 1

   Open Developers › API

   In the sidebar, under Developers, click API. The Keys tab opens. Only workspace owners and admins see this page.

2. 2

   Create a key

   Click Create key and name it after the system that will use it, for example Store production. Every key can send messages, so you don't need to give it any extra access.

   

   

3. 3

   Copy it now

   Copy the key from Copy your new key and store it in your server's secrets. You won't see it again. If you lose it, rotate the key.

4. 4

   Send it on every request

   Put the key in the x-agentim-token header.

Use one key per system, so you can rotate or revoke it on its own. You can also limit a key's requests per minute, chatbots and expiry date. See Developers.

Integrations you set up earlier keep working with the Legacy token (the account token) shown on the same page, in the same header.

Send a message#

POST https://api.agentim.ai/sendMessage with a JSON body:

curl -X POST https://api.agentim.ai/sendMessage \
  -H "Content-Type: application/json" \
  -H "x-agentim-token: YOUR_API_KEY" \
  -d '{
  "node_name": "order_shipped",
  "channel": "meta",
  "customer_phone": "15551234567",
  "data": {
    "order": { "id": "3234379", "total": 84.5, "items": [{ "sku": "TSHIRT-M", "qty": 2 }] },
    "customer": { "name": "Noa" }
  }
}'

const response = await fetch("https://api.agentim.ai/sendMessage", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-agentim-token": process.env.AGENTIM_API_KEY, // YOUR_API_KEY
  },
  body: JSON.stringify({
    node_name: "order_shipped",
    channel: "meta",
    customer_phone: "15551234567",
    data: {
      order: { id: "3234379", total: 84.5, items: [{ sku: "TSHIRT-M", qty: 2 }] },
      customer: { name: "Noa" },
    },
  }),
});

const result = await response.json();
if (!result.success) throw new Error(result.error_message ?? result.err);

import os
import requests

response = requests.post(
    "https://api.agentim.ai/sendMessage",
    headers={"x-agentim-token": os.environ["AGENTIM_API_KEY"]},  # YOUR_API_KEY
    json={
        "node_name": "order_shipped",
        "channel": "meta",
        "customer_phone": "15551234567",
        "data": {
            "order": {"id": "3234379", "total": 84.5, "items": [{"sku": "TSHIRT-M", "qty": 2}]},
            "customer": {"name": "Noa"},
        },
    },
    timeout=15,
)
result = response.json()
if not result.get("success"):
    raise RuntimeError(result.get("error_message") or result.get("err"))

Responses#

Every response is JSON with a success field. On errors, read error_message (some authentication errors use err).

A 200 means Agentim accepted the message and handed it to the channel. Delivery to the customer's phone is reported by WhatsApp, not by this response.

Test before going live#

Click the Catch Hook step on the canvas. The step panel shows everything you need:

1. 1

   Copy the example

   Under Call this step, copy the request in your language. It already has the endpoint and this step's node_name.

   

   

2. 2

   Send a test

   Under Send a test request, keep the officely channel, click Use my number, then Send test request. The message arrives on your own WhatsApp, on any plan. You see the response right there.

3. 3

   See what your system sends

   On the step, click Listen for a test request, then send one real request from your system. You see exactly what arrived. Hover a line and click Copy variable to use that field in a message.

The Recent requests tab shows each call from the last 30 days, and whether it Started, Failed or was Skipped. Requests larger than 64 KB are cut to the first 64 KB.