Custom actions

Build any integration by connecting your chatbot to your own backend with a configurable API call.

Overview

A custom action is a configured API call: when the visitor triggers an action (by intent, button click, or event), DGbot sends a POST request to your HTTPS endpoint with conversation context. Your endpoint responds with data or a message. DGbot incorporates the response into the conversation.

The custom action system is the foundation of DGbot's extensibility. The Send email action, and any other integration you build, all use the same underlying mechanism.

Implement your endpoint

Your endpoint is a standard HTTPS POST handler. It receives the request, does something useful (database lookup, external API call, business logic), and returns a JSON response.

Minimal Python example:

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/dgbot/action")
async def handle_dgbot_action(request: Request):
    body = await request.json()
    payload = body.get("payload", {})
    customer_email = payload.get("customer_email")

    # Your business logic here
    order = await db.get_latest_order(customer_email)

    if order:
        return {
            "message": f"Your latest order #{order.id} is {order.status}."
        }
    else:
        return {
            "message": "I couldn't find any orders for that email address."
        }

Node.js example:

const express = require('express')
const app = express()
app.use(express.json())

app.post('/dgbot/action', async (req, res) => {
  const { payload } = req.body
  const order = await getOrder(payload.customer_email)
  res.json({
    message: order
      ? `Your order #${order.id} is ${order.status}.`
      : "No orders found for that email."
  })
})

Request schema

DGbot sends this JSON body to your endpoint:

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

trigger values: ai_intent, button_click, lead_captured, manual.

Response schema

Return one of these response shapes:

Message response — speak verbatim:

{ "message": "Your order is on the way." }

Data response — bot composes a natural-language response:

{
  "data": {
    "order_id": "12345",
    "status": "shipped",
    "tracking": "UPS 1Z999AA10123456784"
  }
}

Error response — bot says it encountered a problem:

{ "error": "Order not found for that email address." }

HTTP status codes: return 200 for success, 4xx for expected failures (not found, validation error), 5xx for unexpected errors. DGbot handles each appropriately in the conversation.

Configure in admin

See the Custom API action guide in the Tools section for full configuration instructions. Developer-specific notes:

• Timeout: DGbot waits up to 8 seconds for a response. Design your endpoint to respond within 5 seconds.
• Retries: No automatic retries — design your endpoint to be idempotent if your use case requires it.
• Payload size: Request and response bodies are limited to 100 KB.

Security

Verify requests come from DGbot. DGbot includes a signature header with every request. Verify it on your server to ensure requests are genuine:

import hmac, hashlib

def verify_dgbot_signature(request_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        request_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# In your handler:
signature = request.headers.get("X-DGbot-Signature")
is_valid = verify_dgbot_signature(await request.body(), signature, YOUR_WEBHOOK_SECRET)

The webhook secret is shown in the custom action configuration in the admin panel.

Use HTTPS only. DGbot rejects plaintext HTTP endpoints.

Rate limit your endpoint. DGbot rate-limits action calls to 3 per 10 minutes per conversation, but your endpoint should also rate limit by conversation ID to handle any unexpected volume.