Custom Actions

Overview

Custom Actions are configurable buttons that appear in the chat interface, enabling quick integrations with external systems. Actions can call webhooks, open URLs, or execute JavaScript code.

List Custom Actions

Retrieve all custom actions for your organization.

GET /api/custom-actions

Query Parameters

Parameter	Type	Description
`search`	string	Filter by custom action name (case-insensitive)
`page`	integer	Page number for pagination (default: 1)
`limit`	integer	Items per page (default: 50)

Response

{
  "status": "success",
  "data": {
    "custom_actions": [
      {
        "id": "uuid",
        "name": "Create Ticket",
        "icon": "ticket",
        "action_type": "webhook",
        "config": {
          "url": "https://api.helpdesk.com/tickets",
          "method": "POST",
          "headers": { "Authorization": "Bearer token" },
          "body": "{\"subject\": \"{{contact.name}}\"}"
        },
        "is_active": true,
        "display_order": 0,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50
  }
}

Custom Action Redirect

Handles redirects generated by URL action types. Uses a one-time token that expires in 30 seconds.

GET /api/custom-actions/redirect/{token}

Path Parameters

Parameter	Type	Description
`token`	string	The unique single-use redirect token

Response

Returns an HTTP 302 Found redirect to the resolved URL. Returns a 404 Not Found or 410 Gone if the token is invalid or expired.

Get Custom Action

Retrieve a single custom action by ID.

GET /api/custom-actions/{id}

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Create Ticket",
    "icon": "ticket",
    "action_type": "webhook",
    "config": {
      "url": "https://api.helpdesk.com/tickets",
      "method": "POST",
      "headers": {},
      "body": ""
    },
    "is_active": true,
    "display_order": 0,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Create Custom Action

Create a new custom action.

POST /api/custom-actions

Request Body

{
  "name": "Create Support Ticket",
  "icon": "ticket",
  "action_type": "webhook",
  "config": {
    "url": "https://api.helpdesk.com/tickets",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    "body": "{\"subject\": \"WhatsApp: {{contact.name}}\", \"phone\": \"{{contact.phone_number}}\"}"
  },
  "is_active": true,
  "display_order": 0
}

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Display name for the action button
`icon`	string	No	Icon identifier (ticket, user, link, phone, mail, etc.)
`action_type`	string	Yes	Type of action: `webhook`, `url`, or `javascript`
`config`	object	Yes	Configuration object (varies by action type)
`is_active`	boolean	No	Whether the action is enabled (default: true)
`display_order`	integer	No	Sort order for display (default: 0)

Config by Action Type

Webhook Config

{
  "url": "https://api.example.com/endpoint",
  "method": "POST",
  "headers": { "Authorization": "Bearer token" },
  "body": "{\"key\": \"{{contact.phone_number}}\"}"
}

Field	Type	Required	Description
`url`	string	Yes	Webhook endpoint URL
`method`	string	No	HTTP method (POST, GET, PUT, PATCH). Default: POST
`headers`	object	No	Custom HTTP headers
`body`	string	No	JSON request body template

URL Config

{
  "url": "https://crm.example.com/contact?phone={{contact.phone_number}}",
  "open_in_new_tab": true
}

Field	Type	Required	Description
`url`	string	Yes	URL to open
`open_in_new_tab`	boolean	No	Open in new tab (default: true)

JavaScript Config

{
  "code": "return { clipboard: contact.phone_number }"
}

Field	Type	Required	Description
`code`	string	Yes	JavaScript code to execute

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Create Support Ticket",
    "icon": "ticket",
    "action_type": "webhook",
    "config": { ... },
    "is_active": true,
    "display_order": 0,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Update Custom Action

Update an existing custom action.

PUT /api/custom-actions/{id}

Request Body

{
  "name": "Updated Action Name",
  "is_active": false
}

All fields are optional. Only provided fields will be updated.

Delete Custom Action

Delete a custom action.

DELETE /api/custom-actions/{id}

Response

{
  "status": "success",
  "data": {
    "status": "deleted"
  }
}

Execute Custom Action

Execute a custom action for a specific contact.

POST /api/custom-actions/{id}/execute

Request Body

{
  "contact_id": "uuid"
}

Response

The response varies based on action type:

Webhook Response

{
  "status": "success",
  "data": {
    "success": true,
    "message": "Webhook executed successfully",
    "data": { ... },
    "toast": {
      "message": "Webhook executed successfully",
      "type": "success"
    }
  }
}

URL Response

{
  "status": "success",
  "data": {
    "success": true,
    "message": "Opening URL",
    "redirect_url": "/api/custom-actions/redirect/token123"
  }
}

JavaScript Response

{
  "status": "success",
  "data": {
    "success": true,
    "message": "JavaScript action executed",
    "data": {
      "code": "return { clipboard: contact.phone_number }",
      "context": {
        "contact": { ... },
        "user": { ... },
        "organization": { ... }
      }
    },
    "toast": {
      "message": "Action completed",
      "type": "success"
    }
  }
}

Available Variables

Variables can be used in webhook URLs, bodies, and URL templates using {{variable}} syntax:

Variable	Description
`{{contact.id}}`	Contact’s unique ID
`{{contact.phone_number}}`	Contact’s phone number
`{{contact.name}}`	Contact’s display name
`{{contact.profile_name}}`	Contact’s WhatsApp profile name
`{{user.id}}`	Current user’s ID
`{{user.name}}`	Current user’s full name
`{{user.email}}`	Current user’s email
`{{user.role}}`	Current user’s role
`{{organization.id}}`	Organization’s ID
`{{organization.name}}`	Organization’s name

Available Icons

Icon	Description
`ticket`	Support ticket
`user`	User/contact
`bar-chart`	Analytics/chart
`link`	Link
`phone`	Phone
`mail`	Email
`file-text`	Document
`external-link`	External link
`zap`	Quick action
`globe`	Web/globe
`code`	Code/script