Custom API action

Connect your chatbot to any external service or database by configuring a custom API call that fires in response to visitor actions.

~20 minutes Pro

What you can build

A custom API action lets your chatbot call any HTTPS endpoint — your own backend, a third-party API, or a service like Zapier or Make. When the action fires, DGbot sends a configurable POST request and can use the response to generate the bot's reply.

Example use cases:

Real-time inventory check — Call your warehouse API and return live stock levels
Appointment availability — Query your calendar system and show available slots
Account lookup — Look up a customer in your CRM using their email and return their account status
Form submission — Submit the visitor's information to any external form endpoint
Workflow trigger — Start a workflow in your automation platform when a visitor completes a step

Configure a custom action

Open Settings → Integrations → Custom API actions

Go to Settings → Integrations → Custom API actions and click Add action.

Open Custom API actions in admin

tools/custom-api-action-create Screenshot needed — save as: _assets/images/tools/custom-api-action-create.png

The Custom API action editor. Configure endpoint, method, headers, body, and trigger.

Name and describe the action

Give the action a name (internal only) and a description. The description is used by the AI router to understand when to call this action — write it as you would describe the action's purpose to a colleague.

Good description: "Look up a customer's order history in the warehouse system using their email address"

Bad description: "Order API call"

Configure the endpoint

Enter the HTTPS URL of your endpoint. Select the HTTP method (POST is most common).

Configure authentication

Add any required headers:

Header	Value
`Authorization`	`Bearer YOUR_SECRET_TOKEN`
`X-API-Key`	`your-api-key`
`Content-Type`	`application/json` (set automatically)

Define the request body

Define the JSON payload DGbot sends to your endpoint. Use template variables to include conversation context:

json

{
  "customer_email": "{{user_email}}",
  "conversation_id": "{{conversation_id}}",
  "query": "{{user_message}}"
}

Variable	Value
`{{user_email}}`	Visitor's email (from lead capture)
`{{user_name}}`	Visitor's name
`{{user_message}}`	The visitor's last message
`{{conversation_id}}`	Unique conversation ID
`{{chatbot_id}}`	Your chatbot's ID

Configure the trigger

Choose when the action fires:

AI-triggered — The AI router calls this action when visitor intent matches the description you wrote in step 2
Button click — A button appears in the chat; the visitor clicks it to trigger the action
After lead capture — Fires automatically after the lead form is submitted

Request format

DGbot sends a POST request to your endpoint with this structure:

json

{
  "action_id": "action_abc123",
  "conversation_id": "conv_xyz789",
  "chatbot_id": "bot_def456",
  "trigger": "ai_intent",
  "payload": {
    // your configured body template, with variables resolved
  },
  "metadata": {
    "visitor_id": "visitor_111",
    "timestamp": "2025-05-15T10:30:00Z"
  }
}

Handle the response

Your endpoint's response determines what the bot says next.

Simple response (just a message):

json

{
  "message": "Your order #12345 is out for delivery and due today by 8pm."
}

Structured response (bot composes the message):

json

{
  "data": {
    "order_number": "12345",
    "status": "out_for_delivery",
    "eta": "2025-05-15T20:00:00Z"
  }
}

If you return "message", the bot speaks it verbatim. If you return "data", the bot uses its AI to compose a natural-language response from the structured data.

Example configurations

Look up order status in a custom system

json

// Request body template
{
  "order_id": "{{user_message}}",
  "tenant_id": "your-tenant-id"
}
// Endpoint: https://api.yourwarehouse.com/orders/lookup
// Trigger: AI-triggered
// Description: "Look up order status when customer provides an order number or asks where their order is"

Submit a contact form to HubSpot via Zapier

json

// Request body template
{
  "email": "{{user_email}}",
  "name": "{{user_name}}",
  "source": "chatbot",
  "conversation_id": "{{conversation_id}}"
}
// Endpoint: https://hooks.zapier.com/hooks/catch/YOUR_ZAP_ID/
// Trigger: After lead capture

Previous Send email Next Appointment booking