Skip to content

Functions

Functions let your assistant do things, not just answer. For example, it can check order status, look up free appointment slots, or create a booking through your own API, then reply with the result. Functions are available on the Startup plan and above.

How a call works

Section titled “How a call works”
  1. A visitor asks something that one of your functions can handle.
  2. The assistant decides to call it and fills in the arguments from the conversation.
  3. PageClerk checks the call before anything is sent:
    • Did the visitor actually ask for this?
    • Is someone trying to trick the assistant into it, for example with hidden instructions or by pretending to be staff?
    • Did the visitor give every argument value, or would the assistant be guessing?
  4. If the check passes, PageClerk calls your endpoint and the assistant answers from the response.

If the check fails, nothing is sent. The assistant asks the visitor to confirm what they want instead. Calls that change data (POST, PUT, DELETE) need more certainty than GET calls, which only read data. If the check itself can’t run, GET calls still go ahead and the others are skipped.

For example, a visitor asks “Can someone come Thursday morning?” and the assistant tries to call book_callout with an address the visitor never gave. The check blocks it, and the assistant asks for the address and a preferred time instead. Once the visitor answers, the next call goes through.

The assistant makes at most one function call per reply, and your endpoint has 8 seconds to respond. Up to the first 8,000 characters of the response are passed to the assistant.

Add a function

Section titled “Add a function”

Open your chatbot and go to Functions. For each function, set:

Field What to enter
Name Letters, numbers and underscores, e.g. check_availability
Description for AI When the assistant should call it, e.g. “Look up free appointment slots for a date”
Endpoint URL A public https URL
HTTP method GET, POST, PUT or DELETE
Parameters The arguments the assistant must collect, with a type and description each
Headers Optional. Up to 5, e.g. Authorization: Bearer … for an API key. Values are encrypted when you save and never shown again; leave a value blank to keep the saved one
Status text Optional. Shown to the visitor while the call runs, e.g. “Checking availability…”. Defaults to “Working on it…”

Write descriptions as if briefing a new colleague. The assistant relies on them to know when to call the function and what each parameter means.

After saving, use Test this function on each function to send sample arguments to your endpoint and see the response. Tests skip the safety check and don’t count toward your messages.

The request

Section titled “The request”
  • GET and DELETE send the arguments as query parameters: https://api.example.com/slots?date=2026-10-16
  • POST and PUT send them as a JSON body: {"date": "2026-10-16"}

Headers you added are sent with every call. PageClerk also sends these, which you can’t override:

Header Value
X-PageClerk-Tool The function name
X-PageClerk-Chatbot Your chatbot ID
X-PageClerk-Conversation The visitor’s conversation ID
X-PageClerk-Signature t=<unix seconds>,v1=<hex>

Verify the signature

Section titled “Verify the signature”

Your signing secret is shown on the Functions page after you save your first function. The signature works like webhook signatures: an HMAC-SHA256, keyed with the secret, of <t>.<payload>, where the payload is:

  • the raw JSON body for POST and PUT
  • the query string without the leading ? for GET and DELETE, e.g. date=2026-10-16

Reject requests with a missing or invalid signature, or a timestamp more than 5 minutes old.

Responses

Section titled “Responses”

Return JSON or plain text. The assistant sees the status code and the body, so a clear error such as {"error": "No slots on that date"} lets it explain the problem to the visitor. Don’t return data the visitor shouldn’t see: the assistant may repeat anything in the response.

See what happened

Section titled “See what happened”

In Chats, replies that used a function show a line underneath with the function name and the result: ran, blocked (and which check failed), skipped, or the error your endpoint returned. Open it to see the arguments and the start of the response. Use the Used a function and Blocked filters to find these conversations.

On the Functions page, each function shows its calls, success rate, blocks and latest error over the last 7 days.