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

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 |