Chatarmin WhatsApp (remote templates)

Overview

Chatarmin is a cidaas chat communication provider for WhatsApp. Message templates are created and approved in Chatarmin. In cidaas you configure the 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. Chatarmin holds the approved template; cidaas stores only the placeholder-to-attribute mapping and the values you send at runtime.

Who this is for

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 Chatarmin
• 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 Chatarmin templates

Prerequisites

• A Chatarmin account with WhatsApp templates you can create and get approved
• A cidaas instance where you can configure providers in CSpace
• Access token with permission to update template groups, manage remote template mappings, and send notifications
• Familiarity with the developer template group — see Developer templates

How it works

1. Configure the Chatarmin provider in CSpace and note the serviceSetupId.
2. Enable remote templates for chat on the developer template group.
3. Create and approve a WhatsApp template in Chatarmin named {groupId}_{templateKey}.
4. Store a remote template mapping in cidaas (placeholders → attribute keys).
5. Send a notification with commMethod: chat, matching groupId / 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.

Locale-specific templates

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 — Configure Chatarmin in CSpace

Provider configuration is managed in CSpace (not via a public create/update API).

1. Open CSpace and go to your instance communication / service settings.
2. Add a Chatarmin (WhatsApp chat) provider.
3. Enter:
   • API key — from your Chatarmin account
   • Sender address — WhatsApp sender number in E.164 format (for example +4915735984120)
4. Complete any verification steps shown in CSpace (for example QR pairing).
5. Save and copy the provider configuration ID (serviceSetupId). You need it in Steps 2 and 4.

When a Chatarmin provider is configured, 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 Chatarmin template instead of a locally stored chat body.

Preferred (when available): In Trust Desk, open Communication → template group developer → Communication provider → Chat. Select your 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 the Chatarmin dashboard, 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	Chatarmin provider configuration ID
remoteTemplateId	Yes	Chatarmin template name ({groupId}_{templateKey}); max 100 characters
commMethod	Yes	Always "chat" for WhatsApp via Chatarmin
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 a 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"]
    }
  ]
}

API Explorer

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

• Chatarmin provider configured and verified in CSpace; serviceSetupId noted
• Remote templates enabled for chat on the developer group
• 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	Provider active and verified in CSpace; recipient number format
Empty or wrong placeholders	customAttributes keys match mapping attribute values
Template not found	Chatarmin name 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

info

Need Support?

For any further assistance, feel free to visit our Support Portal.