Skip to content

Commit ac141a6

Browse files
shridarpatilshridarpatil
committed
Add named parameters docs and custom actions documentation
- Document named template parameters ({{name}} vs {{1}}) in features and API reference - Add custom actions feature docs with webhook, URL, and JavaScript action types - Add custom actions API reference with CRUD and execute endpoints - Update sidebar navigation to include custom actions
1 parent 8cb4030 commit ac141a6

File tree

5 files changed

+564
-2
lines changed

5 files changed

+564
-2
lines changed

‎docs/astro.config.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ export default defineConfig({
2727
{ label: 'Roles & Permissions', slug: 'features/roles-permissions' },
2828
{ label: 'Chatbot Automation', slug: 'features/chatbot' },
2929
{ label: 'Canned Responses', slug: 'features/canned-responses' },
30+
{ label: 'Custom Actions', slug: 'features/custom-actions' },
3031
{ label: 'Templates', slug: 'features/templates' },
3132
{ label: 'Campaigns', slug: 'features/campaigns' },
3233
{ label: 'WhatsApp Flows', slug: 'features/whatsapp-flows' },
@@ -48,6 +49,7 @@ export default defineConfig({
4849
{ label: 'Campaigns', slug: 'api-reference/campaigns' },
4950
{ label: 'Chatbot', slug: 'api-reference/chatbot' },
5051
{ label: 'Canned Responses', slug: 'api-reference/canned-responses' },
52+
{ label: 'Custom Actions', slug: 'api-reference/custom-actions' },
5153
{ label: 'Webhooks', slug: 'api-reference/webhooks' },
5254
{ label: 'Analytics', slug: 'api-reference/analytics' },
5355
],

‎docs/src/content/docs/api-reference/custom-actions.mdx‎

Lines changed: 334 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,334 @@
1+
---
2+
title: Custom Actions
3+
description: API endpoints for managing custom action buttons
4+
---
5+
6+
import { Aside } from '@astrojs/starlight/components';
7+
8+
## Overview
9+
10+
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.
11+
12+
## List Custom Actions
13+
14+
Retrieve all custom actions for your organization.
15+
16+
```bash
17+
GET /api/custom-actions
18+
```
19+
20+
### Response
21+
22+
```json
23+
{
24+
"status": "success",
25+
"data": {
26+
"custom_actions": [
27+
{
28+
"id": "uuid",
29+
"name": "Create Ticket",
30+
"icon": "ticket",
31+
"action_type": "webhook",
32+
"config": {
33+
"url": "https://api.helpdesk.com/tickets",
34+
"method": "POST",
35+
"headers": { "Authorization": "Bearer token" },
36+
"body": "{\"subject\": \"{{contact.name}}\"}"
37+
},
38+
"is_active": true,
39+
"display_order": 0,
40+
"created_at": "2024-01-01T00:00:00Z",
41+
"updated_at": "2024-01-01T00:00:00Z"
42+
}
43+
]
44+
}
45+
}
46+
```
47+
48+
## Get Custom Action
49+
50+
Retrieve a single custom action by ID.
51+
52+
```bash
53+
GET /api/custom-actions/{id}
54+
```
55+
56+
### Response
57+
58+
```json
59+
{
60+
"status": "success",
61+
"data": {
62+
"id": "uuid",
63+
"name": "Create Ticket",
64+
"icon": "ticket",
65+
"action_type": "webhook",
66+
"config": {
67+
"url": "https://api.helpdesk.com/tickets",
68+
"method": "POST",
69+
"headers": {},
70+
"body": ""
71+
},
72+
"is_active": true,
73+
"display_order": 0,
74+
"created_at": "2024-01-01T00:00:00Z",
75+
"updated_at": "2024-01-01T00:00:00Z"
76+
}
77+
}
78+
```
79+
80+
## Create Custom Action
81+
82+
Create a new custom action.
83+
84+
```bash
85+
POST /api/custom-actions
86+
```
87+
88+
### Request Body
89+
90+
```json
91+
{
92+
"name": "Create Support Ticket",
93+
"icon": "ticket",
94+
"action_type": "webhook",
95+
"config": {
96+
"url": "https://api.helpdesk.com/tickets",
97+
"method": "POST",
98+
"headers": {
99+
"Authorization": "Bearer YOUR_API_KEY",
100+
"Content-Type": "application/json"
101+
},
102+
"body": "{\"subject\": \"WhatsApp: {{contact.name}}\", \"phone\": \"{{contact.phone_number}}\"}"
103+
},
104+
"is_active": true,
105+
"display_order": 0
106+
}
107+
```
108+
109+
### Parameters
110+
111+
| Parameter | Type | Required | Description |
112+
|-----------|------|----------|-------------|
113+
| `name` | string | Yes | Display name for the action button |
114+
| `icon` | string | No | Icon identifier (ticket, user, link, phone, mail, etc.) |
115+
| `action_type` | string | Yes | Type of action: `webhook`, `url`, or `javascript` |
116+
| `config` | object | Yes | Configuration object (varies by action type) |
117+
| `is_active` | boolean | No | Whether the action is enabled (default: true) |
118+
| `display_order` | integer | No | Sort order for display (default: 0) |
119+
120+
### Config by Action Type
121+
122+
#### Webhook Config
123+
124+
```json
125+
{
126+
"url": "https://api.example.com/endpoint",
127+
"method": "POST",
128+
"headers": { "Authorization": "Bearer token" },
129+
"body": "{\"key\": \"{{contact.phone_number}}\"}"
130+
}
131+
```
132+
133+
| Field | Type | Required | Description |
134+
|-------|------|----------|-------------|
135+
| `url` | string | Yes | Webhook endpoint URL |
136+
| `method` | string | No | HTTP method (POST, GET, PUT, PATCH). Default: POST |
137+
| `headers` | object | No | Custom HTTP headers |
138+
| `body` | string | No | JSON request body template |
139+
140+
#### URL Config
141+
142+
```json
143+
{
144+
"url": "https://crm.example.com/contact?phone={{contact.phone_number}}",
145+
"open_in_new_tab": true
146+
}
147+
```
148+
149+
| Field | Type | Required | Description |
150+
|-------|------|----------|-------------|
151+
| `url` | string | Yes | URL to open |
152+
| `open_in_new_tab` | boolean | No | Open in new tab (default: true) |
153+
154+
#### JavaScript Config
155+
156+
```json
157+
{
158+
"code": "return { clipboard: contact.phone_number }"
159+
}
160+
```
161+
162+
| Field | Type | Required | Description |
163+
|-------|------|----------|-------------|
164+
| `code` | string | Yes | JavaScript code to execute |
165+
166+
### Response
167+
168+
```json
169+
{
170+
"status": "success",
171+
"data": {
172+
"id": "uuid",
173+
"name": "Create Support Ticket",
174+
"icon": "ticket",
175+
"action_type": "webhook",
176+
"config": { ... },
177+
"is_active": true,
178+
"display_order": 0,
179+
"created_at": "2024-01-01T00:00:00Z",
180+
"updated_at": "2024-01-01T00:00:00Z"
181+
}
182+
}
183+
```
184+
185+
## Update Custom Action
186+
187+
Update an existing custom action.
188+
189+
```bash
190+
PUT /api/custom-actions/{id}
191+
```
192+
193+
### Request Body
194+
195+
```json
196+
{
197+
"name": "Updated Action Name",
198+
"is_active": false
199+
}
200+
```
201+
202+
All fields are optional. Only provided fields will be updated.
203+
204+
## Delete Custom Action
205+
206+
Delete a custom action.
207+
208+
```bash
209+
DELETE /api/custom-actions/{id}
210+
```
211+
212+
### Response
213+
214+
```json
215+
{
216+
"status": "success",
217+
"data": {
218+
"status": "deleted"
219+
}
220+
}
221+
```
222+
223+
## Execute Custom Action
224+
225+
Execute a custom action for a specific contact.
226+
227+
```bash
228+
POST /api/custom-actions/{id}/execute
229+
```
230+
231+
### Request Body
232+
233+
```json
234+
{
235+
"contact_id": "uuid"
236+
}
237+
```
238+
239+
### Response
240+
241+
The response varies based on action type:
242+
243+
#### Webhook Response
244+
245+
```json
246+
{
247+
"status": "success",
248+
"data": {
249+
"success": true,
250+
"message": "Webhook executed successfully",
251+
"data": { ... },
252+
"toast": {
253+
"message": "Webhook executed successfully",
254+
"type": "success"
255+
}
256+
}
257+
}
258+
```
259+
260+
#### URL Response
261+
262+
```json
263+
{
264+
"status": "success",
265+
"data": {
266+
"success": true,
267+
"message": "Opening URL",
268+
"redirect_url": "/api/custom-actions/redirect/token123"
269+
}
270+
}
271+
```
272+
273+
#### JavaScript Response
274+
275+
```json
276+
{
277+
"status": "success",
278+
"data": {
279+
"success": true,
280+
"message": "JavaScript action executed",
281+
"data": {
282+
"code": "return { clipboard: contact.phone_number }",
283+
"context": {
284+
"contact": { ... },
285+
"user": { ... },
286+
"organization": { ... }
287+
}
288+
},
289+
"toast": {
290+
"message": "Action completed",
291+
"type": "success"
292+
}
293+
}
294+
}
295+
```
296+
297+
## Available Variables
298+
299+
Variables can be used in webhook URLs, bodies, and URL templates using `{{variable}}` syntax:
300+
301+
| Variable | Description |
302+
|----------|-------------|
303+
| `{{contact.id}}` | Contact's unique ID |
304+
| `{{contact.phone_number}}` | Contact's phone number |
305+
| `{{contact.name}}` | Contact's display name |
306+
| `{{contact.profile_name}}` | Contact's WhatsApp profile name |
307+
| `{{contact.tags}}` | Contact's tags (comma-separated) |
308+
| `{{contact.metadata}}` | Contact's custom metadata |
309+
| `{{user.id}}` | Current user's ID |
310+
| `{{user.name}}` | Current user's full name |
311+
| `{{user.email}}` | Current user's email |
312+
| `{{user.role}}` | Current user's role |
313+
| `{{organization.id}}` | Organization's ID |
314+
| `{{organization.name}}` | Organization's name |
315+
316+
## Available Icons
317+
318+
| Icon | Description |
319+
|------|-------------|
320+
| `ticket` | Support ticket |
321+
| `user` | User/contact |
322+
| `bar-chart` | Analytics/chart |
323+
| `link` | Link |
324+
| `phone` | Phone |
325+
| `mail` | Email |
326+
| `file-text` | Document |
327+
| `external-link` | External link |
328+
| `zap` | Quick action |
329+
| `globe` | Web/globe |
330+
| `code` | Code/script |
331+
332+
<Aside type="note">
333+
Custom actions are scoped to the organization. Each user in the organization will see the same set of custom actions in their chat interface.
334+
</Aside>

0 commit comments

Comments
 (0)