Skip to main content
Use this when your bot needs a live answer from your own system mid-chat – an order status, a price, a stock count. An API / Webhook action lets your bot call your own API in the middle of a conversation. There’s no form for the visitor to fill in. The bot gathers what it needs from the chat, calls your endpoint, and uses the response to keep answering. A travel agency could check live prices this way. An online coffee store could add a “Check order status” action that looks up an order by its number.

​
How it works

  1. The visitor asks something your bot can’t answer from its training alone – like “Where’s order 4172?”.
  2. The AI fills in the request from the chat (here, the order number) and calls your endpoint.
  3. Your API replies with the data.
  4. Chatref feeds that reply back to the bot, which uses it to finish its answer – “Order 4172 shipped yesterday and arrives Friday.”

​
What you configure

  • Method – the HTTP method, defaulting to POST. You can also pick GET, PUT, PATCH, or DELETE.
  • URL – your API endpoint.
  • Request Body Fields – the inputs the AI fills from the chat. Each field has a Field Name, a type, whether it’s Required, and a Description that tells the AI what to put there. These become the inputs the bot supplies when it calls your API.
  • Headers – extra header keys and values. Put auth tokens here.
1

Open the Actions tab

In your agent’s dashboard, go to the Actions tab and create a new action.
2

Choose API / Webhook

Pick API / Webhook as the action type.
3

Name it and describe when to use it

Name the action, like “Check order status”, and write a description that tells the AI when to call it – for example, “Use this to look up an order by its order number.”
4

Set the method and URL

Choose the Method (default POST) and enter your endpoint URL.
5

Add request body fields

Click Add Field for each input the AI should send – for an order lookup, one field named orderNumber. Add a Description for each so the AI knows what value to fill in.
6

Add headers and save

Click Add Header for any auth tokens or content type your endpoint needs, then save. Your bot can now call your API whenever the chat matches your description.
Secure your endpoint. The bot can call it with values it gathered from a public chat, so your API should validate every request and only return data that’s safe to share. Keep secrets – API keys, tokens – in Headers, never in the URL or a request field.

​
Seeing calls

Each call is recorded in the Action Submissions table – see Custom Actions for how to read it. GET lookups are not recorded; other methods are.

​
Next steps

Custom Actions

How actions work and the three types.

Form action

Collect details from the visitor instead.

Button action

Show a one-tap button in the chat.

Knowledge Base

Train your bot on your own content.