Create a template
Creates any supported template type. Official WhatsApp templates are submitted to Meta according to the approved sender. Name must be lowercase English with underscores. Attach header media in the same multipart request, or upload first via /api/v2/templates/media then pass headerAssetId.
When to use it. When your system must create templates programmatically and send them after approval.
Code example
Correct: Full WhatsApp template (image + variables + buttons)
curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"order_ready_notice","category":"whatsapp","subType":"utility","language":"ar","headerType":"image","headerAssetId":"ASSET_ID_FROM_MEDIA_UPLOAD","body":"مرحباً {{1}}، طلبك رقم {{2}} جاهز للاستلام. الإجمالي {{3}} ل.س.","bodyParameters":[{"index":1,"label":"أحمد"},{"index":2,"label":"A-1042"},{"index":3,"label":"25000"}],"footer":"راسل","buttons":[{"type":"url","text":"تتبع الطلب","url":"https://example.com/orders/{{1}}","urlExample":"https://example.com/orders/A-1042"},{"type":"phone","text":"اتصل بنا","url":"+963911111111"}]}'Correct: WhatsApp template with document in one request
curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"invoice_notice","category":"whatsapp","subType":"utility","language":"ar","headerType":"document","body":"فاتورتك رقم {{1}} جاهزة.","headerMedia":"<multipart binary PDF>","payload":"{\"bodyParameters\":[{\"index\":1,\"label\":\"A-1042\"}]}","note":"Content-Type: multipart/form-data"}'Correct: SMS template
curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"sms_otp","category":"sms","subType":"otp","content":"رمز التحقق هو {{1}}"}'Incorrect: Incorrect: Arabic template name
curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"تأكيد_الطلب","category":"whatsapp","body":"مرحباً"}'Name must be lowercase English with underscores.
Official WhatsApp utility template with header media
curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"order_ready_notice","category":"whatsapp","subType":"utility","language":"ar","headerType":"image","headerAssetId":"ASSET_ID_FROM_MEDIA_UPLOAD","body":"مرحباً {{1}}، طلبك رقم {{2}} جاهز للاستلام. الإجمالي {{3}} ل.س.","bodyParameters":[{"index":1,"label":"أحمد"},{"index":2,"label":"A-1042"},{"index":3,"label":"25000"}],"footer":"راسل","buttons":[{"type":"url","text":"تتبع الطلب","url":"https://example.com/orders/{{1}}","urlExample":"https://example.com/orders/A-1042"},{"type":"phone","text":"اتصل بنا","url":"+963911111111"}]}'JSON path: upload an image via POST /api/v2/templates/media and replace headerAssetId, or send the same fields as multipart with headerMedia. {{1}} {{2}} {{3}} in body are filled from bodyParameters labels (examples for Meta) and later from variablesIndexed when sending. URL button uses {{1}} in the path; send the suffix with template.buttonVariables. Phone button dials the number in url.
WhatsApp utility (body only)
curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"order_confirmation","category":"whatsapp","subType":"utility","language":"ar","body":"مرحباً {{1}}، طلبك رقم {{2}} تم تأكيده.","bodyParameters":[{"index":1,"label":"أحمد"},{"index":2,"label":"12345"}]}'WhatsApp OTP copy code
curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"login_otp","category":"whatsapp","subType":"otp","language":"ar","otpType":"copy_code","addSecurityRecommendation":true,"codeExpirationMinutes":10,"otpButtonText":"Copy code"}'WhatsApp Web session template
curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"session_welcome","category":"whatsapp","subType":"utility","language":"ar","provider":"user_session","body":"مرحباً {{1}}، شكراً لتواصلك معنا."}'SMS template
curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"sms_otp","category":"sms","subType":"otp","content":"رمز التحقق هو {{1}}"}'Email template
curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"welcome_email","category":"email","subType":"utility","emailSubject":"Welcome","content":"<p>Hello {{1}}</p>"}'Bind existing official WhatsApp template
curl --location 'https://raselsms.com/api/v2/templates' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"name":"eshaar_order_status","creationMode":"manual_external_id","providerTemplateId":"1234567890","subType":"utility","language":"ar","manualVariableCount":2}'Response example
201 — Full WhatsApp template (image + variables + buttons)
{ "success": true, "data": { "template": { "id": "6800tpl123def4567890aaaa", "name": "order_ready_notice", "category": "whatsapp", "subType": "utility", "language": "ar", "status": "pending", "headerType": "image", "headerValue": null, "headerAssetId": null, "headerPreviewUrl": null, "allowsHeaderMediaOverride": true, "provider": "meta", "officialSenderId": "platform", "officialSender": { "id": "platform", "scope": "platform", "isPlatform": true, "isDefault": true, "label": null, "phoneNumber": null, "displayName": "platform" }, "isPlatformNumber": true, "isDefault": false, "createdAt": "2026-09-01T10:00:00.000Z" } }}201 — WhatsApp template with document in one request
{ "success": true, "data": { "template": { "id": "6800tpl123def4567890aaaa", "name": "invoice_notice", "category": "whatsapp", "subType": "utility", "language": "ar", "status": "pending", "headerType": "image", "headerValue": null, "headerAssetId": null, "headerPreviewUrl": null, "allowsHeaderMediaOverride": true, "provider": "meta", "officialSenderId": "platform", "officialSender": { "id": "platform", "scope": "platform", "isPlatform": true, "isDefault": true, "label": null, "phoneNumber": null, "displayName": "platform" }, "isPlatformNumber": true, "isDefault": false, "createdAt": "2026-09-01T10:00:00.000Z" } }}201 — SMS template
{ "success": true, "data": { "template": { "id": "6800tplsms", "name": "sms_otp", "category": "sms", "status": "active" } }}400 — Incorrect: Arabic template name
{ "success": false, "code": "VALIDATION_ERROR", "error": "Invalid template name"}Name must be lowercase English with underscores.
401 — Missing or invalid API key.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "UNAUTHORIZED", "error": "Missing or invalid API key"}403 — Phone is not verified or the key lacks permission (usually messages:create or api_keys:read).
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "FORBIDDEN", "error": "Phone not verified or missing permission"}429 — Rate limit exceeded. Honor Retry-After when present.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "RATE_LIMITED", "error": "Rate limit exceeded", "retryAfterSeconds": 30}HTTP request
POST /api/v2/templates
Request Headers
| Header | Type | Description |
|---|---|---|
| X-API-Key | string | Your Rasel API key. Send it on every documented request except inbound webhooks. * |
Request body
| Field | Type | Description | Example |
|---|---|---|---|
| name | string | Display name or lowercase template identifier, depending on the endpoint. * | |
| category | enum | Template category: whatsapp, sms, message, or email. * | |
| subType | enum | Template sub-type such as utility, otp, marketing, or free. * | |
| language | string | Meta template language such as ar or en. Used for official WhatsApp templates. | |
| body | string | WhatsApp template body with numbered placeholders. Pair with bodyParameters at create and variablesIndexed at send. | |
| content | string | On unified send: message content object (text, otpCode, or email subject). On templates: SMS or message body, or email HTML/text. | |
| emailSubject | string | Required when category is email. | |
| headerType | enum | Header kind: text, image, video, or document. | |
| headerValue | string | Text header value when headerType is text. | |
| headerAssetId | string | Id from the media upload path. Not required when headerMedia, file, or headerMediaUrl is sent. | |
| footer | string | Optional WhatsApp footer. Not used on WhatsApp Web session templates. | |
| buttons | json | WhatsApp buttons configured on the template. | |
| bodyParameters | json | Example values submitted to Meta for numbered body placeholders. | |
| otpType | enum | Official WhatsApp OTP button type: copy_code, one_tap, or zero_tap. | |
| addSecurityRecommendation | boolean | When true, Meta adds the standard OTP security recommendation line. | |
| codeExpirationMinutes | integer | OTP validity in minutes (1-90) for official WhatsApp OTP templates. | |
| otpButtonText | string | Label on the official WhatsApp OTP copy-code button. | |
| packageName | string | Android package name for one-tap or zero-tap OTP. | |
| signatureHash | string | Android app signature hash for one-tap or zero-tap OTP. | |
| zeroTapTermsAccepted | boolean | Must be true when otpType is zero_tap. | |
| provider | enum | Template provider filter or value: user_session, meta, or internal. | |
| templateTarget | enum | Set to user_session to create a WhatsApp Web session template (same as provider=user_session). | |
| officialSenderId | string | Official WhatsApp sender id from /api/v2/official-senders. Alias of sender.officialId. Use platform for the default Meta number when listing templates. | |
| creationMode | enum | Use manual_external_id to bind an existing official WhatsApp template with providerTemplateId. | |
| providerTemplateId | string | Existing official WhatsApp / Meta template id when binding manually. | |
| manualVariableCount | integer | Number of body variables when binding an existing official template. |
Response Fields
| Field | Type | Description | Example |
|---|---|---|---|
| success | boolean | True when the operation succeeded, or when at least one batch recipient succeeded. | |
| data | object | Primary payload for list and snapshot endpoints. | |
| data.template | object | Template reference (id or key), language, variables, and optional per-send header media. | |
| data.template.id | string | Resource identifier. | |
| data.template.name | string | Display name or lowercase template identifier, depending on the endpoint. | |
| data.template.category | enum | Template category: whatsapp, sms, message, or email. | |
| data.template.subType | enum | Template sub-type such as utility, otp, marketing, or free. | |
| data.template.status | enum | Delivery or record status. On send: sent, queued, or scheduled. On other resources it is the row status filter or value. | |
| data.template.language | string | Meta template language such as ar or en. Used for official WhatsApp templates. | |
| data.template.body | string | WhatsApp template body with numbered placeholders. Pair with bodyParameters at create and variablesIndexed at send. | |
| data.template.bodyParameters | json | Example values submitted to Meta for numbered body placeholders. | |
| data.template.headerType | enum | Header kind: text, image, video, or document. | |
| data.template.headerValue | string | Text header value when headerType is text. | |
| data.template.headerAssetId | string | Id from the media upload path. Not required when headerMedia, file, or headerMediaUrl is sent. | |
| data.template.headerPreviewUrl | string | Preview URL for stored header media. | |
| data.template.allowsHeaderMediaOverride | boolean | True when this official WhatsApp template accepts a per-send header file or URL. | |
| data.template.footer | string | Optional WhatsApp footer. Not used on WhatsApp Web session templates. | |
| data.template.buttons | json | WhatsApp buttons configured on the template. | |
| data.template.urlButtonVariables | json | Values for URL button suffixes on this template. | |
| data.template.indexedPlaceholders | string-list | Numbered body placeholders, such as {{1}}. | |
| data.template.content | string | On unified send: message content object (text, otpCode, or email subject). On templates: SMS or message body, or email HTML/text. | |
| data.template.parameters | json | Example or bound values for the template body placeholders. | |
| data.template.provider | string | Template provider filter or value: user_session, meta, or internal. | |
| data.template.providerTemplateId | string | Existing official WhatsApp / Meta template id when binding manually. | |
| data.template.manualProvider | enum | Provider recorded when this template was bound manually. | |
| data.template.officialSenderId | string | Official WhatsApp sender id from /api/v2/official-senders. Alias of sender.officialId. Use platform for the default Meta number when listing templates. | |
| data.template.officialSender | object | Official WhatsApp number this template is bound to. | |
| data.template.officialSender.id | string | Resource identifier. | |
| data.template.officialSender.scope | enum | platform when the template uses the default number, otherwise a specific sender. | |
| data.template.officialSender.isPlatform | boolean | True when the template uses the platform default number. | |
| data.template.officialSender.isDefault | boolean | True when this sender or template is the account default. | |
| data.template.officialSender.label | string | Ready-to-show sender label combining name and phone. | |
| data.template.officialSender.phoneNumber | string | Verified display number in E.164. | |
| data.template.officialSender.displayName | string | Name shown for this official sender. | |
| data.template.isPlatformNumber | boolean | True when the template is bound to the platform default official number. | |
| data.template.isDefault | boolean | True when this sender or template is the account default. | |
| data.template.createdAt | string | Creation timestamp. | |
| message | string | Human-readable result message from create or upload. |
Status Codes
| Status | Description |
|---|---|
| 201 | Created. |
| 400 | Invalid request, validation error, or the resource cannot be used in this state. |
| 401 | Missing or invalid API key. |
| 403 | Phone not verified, missing permission, or the account cannot perform this action. |
| 409 | Conflict, such as an idempotency key reuse with a different body, or a session that is not ready. |
| 429 | Rate limit exceeded, or the maximum number of verification attempts was reached. |
| 503 | The provider is unavailable or timed out. |
Try it
You are not signed in, or the server rejected this session. Lists stay empty until you sign in or enter a valid API key. Someone else's account is not shown.
Parameters
Official WhatsApp sender id from /api/v2/official-senders. Alias of sender.officialId. Use platform for the default Meta number when listing templates.
Display name or lowercase template identifier, depending on the endpoint.
Template category: whatsapp, sms, message, or email.
Template sub-type such as utility, otp, marketing, or free.
Meta template language such as ar or en. Used for official WhatsApp templates.
WhatsApp template body with numbered placeholders. Pair with bodyParameters at create and variablesIndexed at send.
On unified send: message content object (text, otpCode, or email subject). On templates: SMS or message body, or email HTML/text.
Required when category is email.
Header kind: text, image, video, or document.
Text header value when headerType is text.
Id from the media upload path. Not required when headerMedia, file, or headerMediaUrl is sent.
Optional WhatsApp footer. Not used on WhatsApp Web session templates.
WhatsApp buttons configured on the template.
Example values submitted to Meta for numbered body placeholders.
Official WhatsApp OTP button type: copy_code, one_tap, or zero_tap.
When true, Meta adds the standard OTP security recommendation line.
OTP validity in minutes (1-90) for official WhatsApp OTP templates.
Label on the official WhatsApp OTP copy-code button.
Android package name for one-tap or zero-tap OTP.
Android app signature hash for one-tap or zero-tap OTP.
Must be true when otpType is zero_tap.
Template provider filter or value: user_session, meta, or internal.
Set to user_session to create a WhatsApp Web session template (same as provider=user_session).
Use manual_external_id to bind an existing official WhatsApp template with providerTemplateId.
Existing official WhatsApp / Meta template id when binding manually.
Number of body variables when binding an existing official template.
Request
{ "name": "order_ready_notice", "category": "whatsapp", "subType": "utility", "language": "ar", "headerType": "image", "headerAssetId": "ASSET_ID_FROM_MEDIA_UPLOAD", "body": "مرحباً {{1}}، طلبك رقم {{2}} جاهز للاستلام. الإجمالي {{3}} ل.س.", "bodyParameters": [ { "index": 1, "label": "أحمد" }, { "index": 2, "label": "A-1042" }, { "index": 3, "label": "25000" } ], "footer": "راسل", "buttons": [ { "type": "url", "text": "تتبع الطلب", "url": "https://example.com/orders/{{1}}", "urlExample": "https://example.com/orders/A-1042" }, { "type": "phone", "text": "اتصل بنا", "url": "+963911111111" } ]}Response
Send a request to see the response.