Connect

Catch Hook & API

Start a WhatsApp conversation from your own system, such as an order update from your store, with one HTTP request.

How Catch Hook works#

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

Your system
POST /sendMessage
Catch Hook
order_shipped
Send Message
Hi {{#customer.name}}, order {{#order.id}} shipped

Your store sends an order event; Officely messages the customer with the order details.

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).

Get your API token#

Open My Profile in the app. Under API access, copy the Integrations Token. Send it in the x-officely-token header of every request.

Send a message#

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

Field	Required	Description
`node_name`	Yes	The name of your Catch Hook step.
`channel`	Yes	`meta` (WhatsApp official API), `greenAPI` (your number by QR), or `officely` (preview: sends to your own number).
`customer_phone`	Yes	The customer's WhatsApp number in international format, digits only, for example `15551234567`.
`data`	No	A JSON object. Its fields become variables, such as `{{#order.id}}`.
`node_text`	No	Text added after the step's message.
`replace_text`	No	`true` to send `node_text` instead of the step's message.

curl -X POST https://api.officely.ai/sendMessage \
  -H "Content-Type: application/json" \
  -H "x-officely-token: YOUR_API_TOKEN" \
  -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.officely.ai/sendMessage", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-officely-token": process.env.OFFICELY_API_TOKEN, // YOUR_API_TOKEN
  },
  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.officely.ai/sendMessage",
    headers={"x-officely-token": os.environ["OFFICELY_API_TOKEN"]},  # YOUR_API_TOKEN
    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).

Status	Meaning
`200`	Sent. Body: `{"success": true}`
`400`	A required field is missing, for example `"'node_name' Is Required..!"`.
`401`	Missing token (`"Token Required!"`) or invalid token (`"Invalid Token!"`).
`406`	The request can't be processed: `node_name` isn't a Catch Hook step, the channel isn't connected yet, `data` isn't an object, or a preview message was addressed to someone other than you.
`422`	`channel` isn't one of the supported values.
`426`	Your plan doesn't include sending to live channels. Upgrade to Pro, or use `"channel": "officely"` to test.
`502`	WhatsApp or the channel provider returned an error. Retry later.
`500`	Unexpected error. Our team is notified automatically.

A 200 means Officely 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#

In the Catch Hook step, open Listen for a test request. It shows the endpoint, the exact node_name to send, and a ready-made example request. Send it with "channel": "officely" and the message arrives on your own WhatsApp, on any plan.

The Recent requests tab shows each call from the last 30 days, whether it started a conversation, and the payload it carried. Click any field in a payload to copy it as a variable. Officely doesn't store your token, and bodies are capped at 64 KB.