EngageLab OTP API Skill

This skill enables interaction with the EngageLab OTP REST API. The OTP service handles one-time password generation, multi-channel delivery (SMS, WhatsApp, Email, Voice), verification, and fraud monitoring.

It covers six areas:

1. 1. OTP Send — Platform-generated OTP code delivery
2. Custom OTP Send — User-generated OTP code delivery
3. OTP Verify — Validate OTP codes
4. Custom Messages Send — Send custom template messages (notifications, marketing)
5. Template Management — Create, list, get, and delete OTP templates
6. Callback & SMPP — Webhook configuration and SMPP protocol integration

Resources

scripts/

• - otp_client.py — Python client class (EngageLabOTP) wrapping all API endpoints: send_otp(), send_custom_otp(), verify(), send_custom_message(), and template CRUD. Handles authentication, request construction, and typed error handling. Use this as a ready-to-run helper or import it into the user's project.
• verify_callback.py — HMAC-SHA256 signature verifier for incoming OTP callback webhooks. Parses the X-CALLBACK-ID header and validates authenticity. Drop into any web framework (Flask, FastAPI, Django) to secure callback endpoints.

references/

• - error-codes.md — Complete error code tables for all OTP APIs
• template-api.md — Full template CRUD specs with all channel configurations
• callback-config.md — Webhook setup, security, and all event types
• smpp-guide.md — SMPP protocol connection, messaging, and delivery reports

Authentication

All EngageLab OTP API calls use HTTP Basic Authentication.

• - Base URL: INLINECODE12
• Header: INLINECODE13
• Content-Type: INLINECODE14

The user must provide their dev_key and dev_secret. Encode them as base64("dev_key:dev_secret") and set the Authorization header.

Example (using curl):

CODEBLOCK0

If the user hasn't provided credentials, ask them for their dev_key and dev_secret before generating API calls.

Quick Reference — All Endpoints

Operation	Method	Path
Send OTP (platform-generated)	INLINECODE21	INLINECODE22
Send OTP (custom code)

POST | /v1/codes | | Verify OTP | POST | /v1/verifications | | Send custom message | POST | /v1/custom-messages | | List templates | GET | /v1/template-configs | | Get template details | GET | /v1/template-configs/:templateId | | Create template | POST | /v1/template-configs | | Delete template | DELETE | /v1/template-configs/:templateId |

OTP Send (Platform-Generated Code)

Use this when you want EngageLab to generate the verification code and deliver it according to the template's channel strategy (SMS, WhatsApp, Email, Voice).

Endpoint: INLINECODE37

Request Body

CODEBLOCK1

Parameters

Field	Type	Required	Description
INLINECODE38	INLINECODE39	Yes	Phone number (with country code, e.g., +6581234567) or email address
INLINECODE41

string | Yes | Template ID | | template.language | string | No | Language: default, zh_CN, zh_HK, en, ja, th, es. Defaults to default | | template.params | object | No | Custom template variable values as key-value pairs |

Notes on params

• - Preset variables like {{brand_name}}, {{ttl}}, {{pwa_url}} are auto-filled from template settings — no need to pass them.
• For custom variables in the template (e.g., Hi {{name}}, your code is {{code}}), pass values via params: {"name": "Bob"}.
• If the template's from_id field is preset and you pass {"from_id": "12345"}, the preset value is overridden.

Response

Success:

CODEBLOCK2

Field	Type	Description
INLINECODE63	INLINECODE64	Unique message ID, used for verification and tracking
INLINECODE65

string | Current delivery channel: whatsapp, sms, email, or voice |

The send_channel indicates the initial channel — if fallback is configured (e.g., WhatsApp → SMS), the final delivery channel may differ.

For error codes, read references/error-codes.md.

Custom OTP Send (User-Generated Code)

Use this when you want to generate the verification code yourself and have EngageLab deliver it. This API does not generate codes and does not require calling the Verify API afterward.

Endpoint: INLINECODE73

Request Body

CODEBLOCK3

Parameters

Field	Type	Required	Description
INLINECODE74	INLINECODE75	Yes	Phone number or email address
INLINECODE76

string | Yes | Your custom verification code | | template.id | string | Yes | Template ID | | template.language | string | No | Language (same options as OTP Send). Defaults to default | | template.params | object | No | Custom template variable values |

Response

Same format as OTP Send — returns message_id and send_channel.

OTP Verify

Validate a verification code that was sent via the OTP Send API (/v1/messages). Only applicable to platform-generated codes — not needed for Custom OTP Send.

Endpoint: INLINECODE88

Request Body

CODEBLOCK4

Parameters

Field	Type	Required	Description
INLINECODE89	INLINECODE90	Yes	The message_id returned by INLINECODE92
INLINECODE93

string | Yes | The code the user entered |

Response

Success:

CODEBLOCK5

Field	Type	Description
INLINECODE95	INLINECODE96	Message ID
INLINECODE97

string | The submitted code |
| verified | boolean | true = valid, false = invalid |

Important: Successfully verified codes cannot be verified again — subsequent attempts will fail. Expired codes return error 3003.

Custom Messages Send

Send custom template content (verification codes, notifications, or marketing messages) using templates created on the OTP platform.

Endpoint: INLINECODE104

Request Body

CODEBLOCK6

Parameters

Field	Type	Required	Description
INLINECODE105	INLINECODE106 or INLINECODE107	Yes	Single recipient (string) or multiple (array). Phone number or email
INLINECODE108

string | Yes | Template ID | | template.params | object | No | Template variable values | | template.params.code | string | Conditional | Required if template type is verification code |

Notes on params

• - Preset variables ({{brand_name}}, {{ttl}}, {{pwa_url}}) are auto-replaced from template settings.
• For verification code templates, you must pass {{code}} or an error will occur.
• Custom variables need values via params, e.g., {"name": "Bob"} for Hi {{name}}.

Response

Same format as OTP Send — returns message_id and send_channel.

Use Case Examples

Verification code:
CODEBLOCK7

Notification:
CODEBLOCK8

Marketing:
CODEBLOCK9

Template Management

OTP templates define the message content, channel strategy, and verification code settings. Templates support multi-channel delivery with fallback (e.g., WhatsApp → SMS).

For full request/response details including all channel configurations (WhatsApp, SMS, Voice, Email, PWA), read references/template-api.md.

Quick Summary

Create — INLINECODE124

CODEBLOCK10

List all — GET /v1/template-configs (returns array of templates without detailed content)

Get details — GET /v1/template-configs/:templateId (returns full template with channel configs)

Delete — INLINECODE127

Template Status

Value	Status
1	Pending Review
2

Approved | | 3 | Rejected |

Channel Strategy

Use | to define fallback chains. Examples:

• - "sms" — SMS only
• INLINECODE130 — Try WhatsApp first, fall back to SMS
• INLINECODE131 — WhatsApp → SMS → Email

Supported channels: whatsapp, sms, voice, INLINECODE135

Verification Code Config

Field	Range	Description
INLINECODE136	1–7	1=Numeric, 2=Lowercase, 4=Uppercase. Combine: 3=Numeric+Lowercase
INLINECODE137

4–10 | Code length | | verify_code_ttl | 1–10 | Validity in minutes. With WhatsApp: only 1, 5, or 10 |

Callback Configuration

Configure webhook URLs to receive real-time delivery status, notification events, message responses, and system events.

For the full callback data structures, security mechanisms, and event types, read references/callback-config.md.

SMPP Integration

For TCP-based SMPP protocol integration (used in carrier-level SMS delivery), read references/smpp-guide.md.

Generating Code

When the user asks to send OTPs or manage templates, generate working code. Default to curl unless the user specifies a language. Supported patterns:

• - curl — Shell commands with proper auth header
• Python — Using requests library
• Node.js — Using fetch or INLINECODE144
• Java — Using INLINECODE145
• Go — Using INLINECODE146

Always include the authentication header and proper error handling. Use placeholder values like YOUR_DEV_KEY and YOUR_DEV_SECRET if the user hasn't provided credentials.

Python Example — Send OTP and Verify

CODEBLOCK11