ReferenceIntegrations

Custom Actions

API endpoints for managing custom action buttons

DevelopersUpdated 9 Oct 2026

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

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"
      }
    ]
  }
}

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