Chatarmin WhatsApp (remote templates)
Overview
cidaas supports Chatarmin, an external WhatsApp messaging service, as a chat communication provider. You create and get WhatsApp message templates approved in Chatarmin. In cidaas you connect that provider, map Chatarmin placeholders to your notification attributes, and send messages through the Send Template-Based Notifications API.
This flow uses remote templates: cidaas does not store the WhatsApp body locally. The approved template stays in Chatarmin; cidaas stores only the placeholder-to-attribute mapping and the values you send at runtime.
Use this guide when your application sends business WhatsApp messages (for example order or welcome chats) via the developer template group. For standard email/SMS identity flows, see Communication providers and Communication templates.
Key benefits
- Reuse WhatsApp-approved templates managed in your Chatarmin account
- Keep personalization in cidaas with clear attribute mappings
- Send through the same notification API as other channels (
commMethod: chat) - Support locale variants when you maintain language-specific templates in Chatarmin
Prerequisites
- An external Chatarmin account with WhatsApp templates you can create and get approved
- A cidaas instance where you can connect providers in CSpace
- Access token with permission to update template groups, manage remote template mappings, and send notifications
- Familiarity with the
developertemplate group — see Developer templates
How it works
- Connect the external Chatarmin provider in CSpace and note the
serviceSetupId. - Enable remote templates for chat on the
developertemplate group. - Create and approve a WhatsApp template in Chatarmin named
{groupId}_{templateKey}. - Store a remote template mapping in cidaas (placeholders → attribute keys).
- Send a notification with
commMethod: chat, matchinggroupId/templateKey, and attribute values.
Template naming
Use the same name in Chatarmin and in the cidaas mapping remoteTemplateId:
{groupId}_{templateKey}
| Part | Example | Used in |
|---|---|---|
groupId | developer | Notification criteria.groupId |
templateKey | welcomeuser | Notification criteria.templateKey |
| Full name | developer_welcomeuser | Chatarmin template name and mapping remoteTemplateId |
Chatarmin allows lowercase letters and underscores only in the template name.
For another language, create a separate Chatarmin template (for example developer_welcomeuser_de) and register it under variants in the mapping (Step 4). The notification still uses groupId + templateKey; criteria.locale selects the variant.
Step 1 — Connect the Chatarmin provider in CSpace
Provider connections are managed in CSpace (not via a public create/update API).
- Open CSpace and go to your instance communication / service settings.
- Add the external Chatarmin (WhatsApp chat) provider.
- Enter:
- API key — from your Chatarmin account
- Sender address — WhatsApp sender number in E.164 format (for example
+4915735984120)
- Complete any verification steps shown in CSpace (for example QR pairing).
- Save and copy the provider configuration ID (
serviceSetupId). You need it in Steps 2 and 4.
When the Chatarmin provider is connected, remote templates are enabled on that provider automatically. You still must enable remote templates on the template group chat channel (Step 2).
Step 2 — Enable remote templates on the developer group
cidaas must use the template from Chatarmin instead of a locally stored chat body.
Preferred (when available): In Trust Desk, open Communication → template group developer → Communication provider → Chat. Select your connected Chatarmin provider and enable Remote templates, then save.
If the UI option is not available yet on your instance, update the group via API (or ask your cidaas administrator):
PUT /notifications-srv/templategroups/{id}
Authorization: Bearer <access-token>
Content-Type: application/json
Replace {id} with the template group id (for the built-in group this is typically developer).
{
"_id": "developer",
"commSettings": {
"chat": {
"communicationMethod": "chat",
"serviceSetupId": "<your-chatarmin-provider-configuration-id>",
"hasRemoteTemplates": true
}
}
}
| Field | Description |
|---|---|
serviceSetupId | Provider configuration ID from Step 1 |
hasRemoteTemplates | Must be true for the chat channel |
See also Update template group.
Step 3 — Create and approve the template in Chatarmin
In your Chatarmin dashboard (outside cidaas), create the WhatsApp template and submit it for approval. Wait until it is approved before sending.
Typical form fields
| Field | Required | What to enter |
|---|---|---|
| Template category | Yes | Category that matches your use case (for example Marketing) |
| Template type | Yes | Usually Normal for custom templates |
| Template name | Yes | {groupId}_{templateKey} — for example developer_welcomeuser |
| Language | Yes | Language of this template; create one template per language if needed |
| Header | No | Optional media header — leave empty unless required |
| Body text | Yes | Body with numbered variables {{1}}, {{2}}, … |
Body placeholders
Example body in Chatarmin:
Hi {{1}}, welcome to our {{2}} store, hope you have a {{3}} experience.
| Chatarmin placeholder | Index | Maps to attribute (Step 4) | Example at send time |
|---|---|---|---|
{{1}} | 1 | firstname | Alex |
{{2}} | 2 | store_name | main_store |
{{3}} | 3 | experience_type | great |
Indices are 1-based and must match the mapping in Step 4.
Step 4 — Store the remote template mapping
Register how Chatarmin placeholders map to the attribute keys you send in notifications.
POST /api/remotetemplateconfigs/{tenantKey}
Authorization: Bearer <access-token>
Content-Type: application/json
Replace {tenantKey} with your cidaas instance identifier (for example cidaas-mycompany-prod).
Example for developer_welcomeuser:
{
"serviceSetupId": "<your-chatarmin-provider-configuration-id>",
"remoteTemplateId": "developer_welcomeuser",
"commMethod": "chat",
"mappings": [
{
"component": "BODY",
"index": 1,
"remotePlaceholder": "1",
"attribute": "firstname"
},
{
"component": "BODY",
"index": 2,
"remotePlaceholder": "2",
"attribute": "store_name"
},
{
"component": "BODY",
"index": 3,
"remotePlaceholder": "3",
"attribute": "experience_type"
}
]
}
Mapping fields
| Field | Required | Purpose |
|---|---|---|
serviceSetupId | Yes | Configuration ID of the connected Chatarmin provider |
remoteTemplateId | Yes | Template name in Chatarmin ({groupId}_{templateKey}); max 100 characters |
commMethod | Yes | Always "chat" for WhatsApp via the Chatarmin provider |
mappings | Recommended | Default placeholder → attribute rows |
variants | No | Per-locale overrides of template id and/or mappings |
component | Yes (per row) | "BODY" for chat body placeholders |
index | Yes* | 1-based position matching {{1}}, {{2}}, … |
remotePlaceholder | Yes* | Provider placeholder id (for example "1") |
attribute | Yes (per row) | Key you send in customAttributes (or merged attributes) |
* At least one of index or remotePlaceholder is required per row. When using index, values must be consecutive starting at 1 (1, 2, 3 — not 1, 3).
Uniqueness
One mapping per combination of:
serviceSetupId + commMethod + remoteTemplateId
Creating a duplicate returns a conflict. To change an existing mapping, use PUT and include the _id from the create response.
Locale variants
{
"serviceSetupId": "<your-chatarmin-provider-configuration-id>",
"remoteTemplateId": "developer_welcomeuser",
"commMethod": "chat",
"mappings": [
{ "component": "BODY", "index": 1, "attribute": "firstname" },
{ "component": "BODY", "index": 2, "attribute": "store_name" },
{ "component": "BODY", "index": 3, "attribute": "experience_type" }
],
"variants": [
{
"locale": "de",
"remoteTemplateId": "developer_welcomeuser_de",
"mappings": [
{ "component": "BODY", "index": 1, "attribute": "firstname" },
{ "component": "BODY", "index": 2, "attribute": "store_name" },
{ "component": "BODY", "index": 3, "attribute": "experience_type" }
]
}
]
}
When criteria.locale is "de", cidaas uses the German variant if configured; otherwise it uses the default mappings.
Common validation rules
| Rule | What to check |
|---|---|
| Unique key | No second mapping for the same provider + chat + template name |
| Provider supports remote templates | Linked setup is the external Chatarmin chat provider |
| Consecutive indices | 1, 2, 3 — no gaps |
component | Only "BODY" for chat |
| Locales | Valid BCP-47 tags; no duplicate locales (case-insensitive); max 20 variants |
| Create vs update | Omit _id on POST; include _id on PUT |
Managing mappings
| Method | Path | Purpose |
|---|---|---|
POST | /api/remotetemplateconfigs/{tenantKey} | Create |
PUT | /api/remotetemplateconfigs/{tenantKey} | Update (body must include _id) |
GET | /api/remotetemplateconfigs/{tenantKey} | List |
GET | /api/remotetemplateconfigs/{tenantKey}/{id} | Get by id |
DELETE | /api/remotetemplateconfigs/{tenantKey}/{id} | Delete |
POST | /api/graph/remotetemplateconfigs/{tenantKey} | Search / filter |
Update example:
PUT /api/remotetemplateconfigs/{tenantKey}
Authorization: Bearer <access-token>
Content-Type: application/json
{
"_id": "<id-from-create-response>",
"serviceSetupId": "<your-chatarmin-provider-configuration-id>",
"remoteTemplateId": "developer_welcomeuser",
"commMethod": "chat",
"mappings": [
{ "component": "BODY", "index": 1, "attribute": "firstname" },
{ "component": "BODY", "index": 2, "attribute": "store_name" },
{ "component": "BODY", "index": 3, "attribute": "experience_type" }
]
}
Search example:
POST /api/graph/remotetemplateconfigs/{tenantKey}
Authorization: Bearer <access-token>
Content-Type: application/json
{
"isInFields": [
{
"field": "remoteTemplateId",
"contains": true,
"values": ["developer_welcomeuser"]
},
{
"field": "commMethod",
"contains": true,
"values": ["chat"]
}
]
}
Remote template config endpoints may not yet appear in the public OpenAPI explorer. Use the paths above against your cidaas host (https://{host}/…). For sending messages, use the documented Send notification API.
Step 5 — Send a WhatsApp notification
POST /notifications-srv/notifications
Authorization: Bearer <access-token>
Content-Type: application/json
{
"criteria": {
"commMethod": "chat",
"groupId": "developer",
"locale": "en",
"templateKey": "welcomeuser"
},
"recipientAddresses": [
{
"address": "+491701234567",
"customAttributes": {
"firstname": "Alex",
"store_name": "main_store",
"experience_type": "great"
}
}
]
}
| Field | Value | Notes |
|---|---|---|
criteria.commMethod | "chat" | WhatsApp / chat channel |
criteria.groupId | "developer" | Must match the group used in the template name |
criteria.templateKey | "welcomeuser" | Combined with groupId → developer_welcomeuser |
criteria.locale | e.g. "en" or "de" | Selects a mapping variant when configured |
recipientAddresses[].address | Phone number | E.164 recommended |
customAttributes | Key / value pairs | Keys must match mapping attribute values |
Resulting Chatarmin placeholders:
{{1}}→Alex{{2}}→main_store{{3}}→great
Full request options: Send Template-Based Notifications.
Checklist
- External Chatarmin provider connected and verified in CSpace;
serviceSetupIdnoted - Remote templates enabled for chat on the
developergroup - WhatsApp template approved in Chatarmin as
{groupId}_{templateKey} - Remote template mapping stored with the same
remoteTemplateId - Placeholder indices match Chatarmin
{{1}},{{2}}, … - Notification sent with matching
groupId,templateKey, and attribute keys
Troubleshooting
| Issue | What to check |
|---|---|
| Message not sent | Connected Chatarmin provider active and verified in CSpace; recipient number format |
| Empty or wrong placeholders | customAttributes keys match mapping attribute values |
| Template not found | Template name in Chatarmin equals {groupId}_{templateKey} and mapping remoteTemplateId |
| Duplicate mapping | Mapping already exists for provider + chat + template name — use PUT |
| Local template used instead of Chatarmin | hasRemoteTemplates is true on the developer group chat settings |
| Wrong language | criteria.locale matches a configured variant |
| Mapping rejected | Consecutive indices, BODY only, valid locales, unique key |
Explore related topics
- Communication Management overview
- Communication providers
- Developer templates
- Send Template-Based Notifications
For any further assistance, feel free to visit our Support Portal.