WhatsApp

The WhatsApp module sends messages to trainees through the studio’s own SmartSend account, stores every message in WhatsappMessage, keeps reusable WhatsappTemplate rows, and exposes the settings the coach web app needs to embed the SmartSend chat. Source: backend/apps/core-api/src/modules/whatsapp/ (whatsapp.routes.ts, whatsapp.controller.ts, whatsapp.service.ts, whatsapp.repository.ts, whatsapp.schema.ts) and the client in backend/packages/smartsend/src/index.ts.

Mounting and auth

The module exports two routers.

Router	Base path	Middleware
`whatsappRouter`	`/v1/web/whatsapp`	Web lane: `serviceAuth`, `webUserContext`, `webLimiter`
`whatsappRouter`	`/v1/whatsapp`	Bearer lane: `replayProtection`, then `authenticate(sessionVerifier)`
`whatsappWebhookRouter`	`/v1/whatsapp/webhook`	None. The handler checks a `token` query parameter itself

/v1/whatsapp/webhook is registered before the bearer /v1/whatsapp mount in modules/index.ts, so webhook calls never reach the bearer authenticate middleware. Every whatsappRouter endpoint reads req.auth.studioId and throws UNAUTHORIZED (401) when it is missing. The routes file applies no requireRole guard, so any role that reaches the lane can call every endpoint, including the ones that change studio settings. See API overview for how each lane builds req.auth. In the tables below, each path is shown for the web lane. The same path exists on the bearer lane with /v1/whatsapp in place of /v1/web/whatsapp.

Where the SmartSend settings live

The service keeps the integration under Studio.settings.smartsend:

type SmartSendSettings = {
  apiKey?: string;
  zapId?: string;
  orgSlug?: string;
  userMap?: Record<string, { id: string; name: string } | undefined>;
};

apiKey is the studio’s SmartSend organization key. Every send, user lookup and mailing list call needs it. When it is missing those endpoints throw BAD_REQUEST (400) with whatsapp is not connected for this studio.

Sending

`POST /v1/web/whatsapp/send`

Also POST /v1/whatsapp/send. Sends one message to one trainee. Auth: web lane or bearer lane, any role.

string

required

The trainee to message. Must belong to the caller’s studio.

string

The message text, at least 1 character. Required when templateId is not sent.

string

A WhatsappTemplate id in the same studio. Used only when body is absent.

object

default:"{}"

String to string map. Fills {{name}} placeholders in the template body. A placeholder with no matching key becomes an empty string. Ignored when body is sent.

string

A valid URL. Passed to SmartSend as mediaUrl.

The schema refines the body so that one of body or templateId is present. What the service does:

Loads the studio’s SmartSend key.
Resolves the text. body wins. Otherwise the template body is loaded and placeholders are replaced.
Loads the client and checks it has a phone.
Calls smartsend.sendMessage with the key, the client’s phone, the text and the optional mediaUrl.
On success it creates a WhatsappMessage row with direction: "OUTBOUND" and status: "SENT".
On failure it still creates an OUTBOUND row with status: "FAILED" and payload: { "error": "..." }, then throws.

Response: 201 with the created WhatsappMessage row.

{
  "ok": true,
  "data": {
    "id": "cmb1x0q5d0001abcd1234efgh",
    "studioId": "cma9s2k1t0000abcd1234efgh",
    "clientId": "cmaz7c3p90004abcd1234efgh",
    "templateId": null,
    "direction": "OUTBOUND",
    "body": "Your check-in is due tomorrow",
    "status": "SENT",
    "externalId": null,
    "payload": null,
    "createdAt": "2026-10-07T08:15:00.000Z",
    "updatedAt": "2026-10-07T08:15:00.000Z"
  },
  "requestId": "req_123"
}

The stored row does not record templateId, even when the text came from a template. Errors:

Code	Status	When
`VALIDATION`	422	Zod rejects the body, including the “body or templateId is required” refinement
`BAD_REQUEST`	400	The studio has no SmartSend key, or the client has no phone number
`NOT_FOUND`	404	`template not found` or `client not found`
`INTERNAL`	500	SmartSend rejected the send (`failed to send whatsapp message`)

`POST /v1/web/whatsapp/bulk`

Also POST /v1/whatsapp/bulk. Sends the same message to several trainees, one after another. Auth: web lane or bearer lane, any role.

string[]

required

At least one client id. The schema sets no upper limit.

string

Message text. Required when templateId is not sent.

string

Template to use when body is absent.

object

default:"{}"

Placeholder values. The same values are used for every recipient.

string

A valid URL.

The text is resolved once, then each client goes through the same send path as the single send. A failure for one client is counted and the loop continues. Each attempt writes its own WhatsappMessage row when the client exists and has a phone. Response: 200.

{
  "ok": true,
  "data": { "total": 3, "sent": 2, "failed": 1 },
  "requestId": "req_123"
}

Errors: VALIDATION (422), BAD_REQUEST (400) when the studio is not connected, NOT_FOUND (404) when templateId does not exist. Per-recipient failures do not fail the request.

Message history

`GET /v1/web/whatsapp/messages`

Also GET /v1/whatsapp/messages. Lists the studio’s messages, newest first. Auth: web lane or bearer lane, any role.

string

Only messages for this client.

string

INBOUND or OUTBOUND.

number

default:"1"

Positive integer.

number

default:"20"

Positive integer, maximum 500.

Response: 200.

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "cmb1x0q5d0001abcd1234efgh",
        "studioId": "cma9s2k1t0000abcd1234efgh",
        "clientId": "cmaz7c3p90004abcd1234efgh",
        "templateId": null,
        "direction": "INBOUND",
        "body": "Thanks!",
        "status": "DELIVERED",
        "externalId": null,
        "payload": { "text": "Thanks!", "type": "chat", "isGroup": false },
        "createdAt": "2026-10-07T08:20:00.000Z",
        "updatedAt": "2026-10-07T08:20:00.000Z"
      }
    ],
    "total": 41,
    "page": 1,
    "pageSize": 20
  },
  "requestId": "req_123"
}

Errors: VALIDATION (422).

`GET /v1/web/whatsapp/chat`

Also GET /v1/whatsapp/chat. One client’s conversation, newest first. Auth: web lane or bearer lane, any role.

string

required

The client whose messages to return.

number

default:"1"

Positive integer.

number

default:"50"

Positive integer, maximum 500.

Response: 200 with items (the same WhatsappMessage shape as above), page and pageSize. There is no total.

{
  "ok": true,
  "data": { "items": [], "page": 1, "pageSize": 50 },
  "requestId": "req_123"
}

Errors: VALIDATION (422), NOT_FOUND (404) client not found.

Templates

A template is a WhatsappTemplate row: id, studioId, name, body, variables (string array), smartsendTemplateId, status, createdAt, updatedAt. These endpoints never set smartsendTemplateId or status.

`GET /v1/web/whatsapp/templates`

Also GET /v1/whatsapp/templates. All templates of the studio, newest first. Auth: web lane or bearer lane, any role. Response: 200 with an array of templates.

{
  "ok": true,
  "data": [
    {
      "id": "cmb2a7m0c0002abcd1234efgh",
      "studioId": "cma9s2k1t0000abcd1234efgh",
      "name": "Check-in reminder",
      "body": "Hi {{name}}, your check-in is due {{day}}",
      "variables": ["name", "day"],
      "smartsendTemplateId": null,
      "status": null,
      "createdAt": "2026-10-01T10:00:00.000Z",
      "updatedAt": "2026-10-01T10:00:00.000Z"
    }
  ],
  "requestId": "req_123"
}

`POST /v1/web/whatsapp/templates`

Also POST /v1/whatsapp/templates. Creates a template. Auth: web lane or bearer lane, any role.

string

required

At least 1 character.

string

required

At least 1 character. Use {{key}} placeholders. Keys may contain letters, digits and underscores.

string[]

default:"[]"

The placeholder names the template expects. Stored as given. The server does not check them against the body.

Response: 201 with the created template. Errors: VALIDATION (422).

`GET /v1/web/whatsapp/templates/:id`

Also GET /v1/whatsapp/templates/:id. One template. Auth: web lane or bearer lane, any role.

string

required

Template id.

Response: 200 with the template. Errors: NOT_FOUND (404) template not found.

`PATCH /v1/web/whatsapp/templates/:id`

Also PATCH /v1/whatsapp/templates/:id. Updates a template. The body is the create body with every field optional. Auth: web lane or bearer lane, any role.

string

required

Template id.

string

New name.

string

New body.

string[]

New variable list.

updateTemplateBody is createTemplateBody.partial(), and the variables field keeps its default([]). A PATCH that omits variables therefore parses to an empty array and clears the stored list. Send variables on every update if you want to keep them.

Response: 200 with the updated template. Errors: VALIDATION (422), NOT_FOUND (404).

`DELETE /v1/web/whatsapp/templates/:id`

Also DELETE /v1/whatsapp/templates/:id. Deletes a template. Auth: web lane or bearer lane, any role. Response: 204 with no body. Errors: NOT_FOUND (404).

Connecting SmartSend

`POST /v1/web/whatsapp/connect`

Also POST /v1/whatsapp/connect. Stores the studio’s SmartSend organization key. Auth: web lane or bearer lane, any role.

string

required

The SmartSend organization key. At least 1 character.

What the service does:

Loads the studio.
Validates the key by calling SmartSend’s users RPC with it (smartsend.listUsers). Any failure means the key is rejected.
Tries to register an inbound webhook with SmartSend, using zapId perform-<studioId> and a hook URL built from PUBLIC_API_URL: /v1/whatsapp/webhook/<studioId>?token=<SMARTSEND_WEBHOOK_SECRET>. This call targets a legacy SmartSend endpoint. A failure is swallowed and does not block connecting.
Merges apiKey and zapId into Studio.settings.smartsend, keeping orgSlug, userMap and all other settings.

Response: 200.

{ "ok": true, "data": { "connected": true }, "requestId": "req_123" }

Errors:

Code	Status	When
`VALIDATION`	422	`apiKey` missing or empty
`NOT_FOUND`	404	`studio not found`
`BAD_REQUEST`	400	`invalid smartsend api key`

There is no disconnect endpoint in this router.

`GET /v1/web/whatsapp/smartsend/users`

Also GET /v1/whatsapp/smartsend/users. Lists the users of the studio’s SmartSend organization, for mapping coaches to SmartSend users. Auth: web lane or bearer lane, any role. Response: 200. Each user is { id, value } where value is the display name returned by SmartSend, or the id when no name is given.

{
  "ok": true,
  "data": {
    "users": [
      { "id": "u_101", "value": "Dana Levi" },
      { "id": "u_102", "value": "Guy Cohen" }
    ]
  },
  "requestId": "req_123"
}

Errors: BAD_REQUEST (400) when the studio is not connected. A SmartSend failure is not mapped to an AppError and surfaces as INTERNAL (500).

`GET /v1/web/whatsapp/smartsend/chat-embed`

Also GET /v1/whatsapp/smartsend/chat-embed. Returns what the workboard needs to embed the SmartSend chat for the calling coach. Auth: web lane or bearer lane, any role. Requires both req.auth.studioId and req.auth.userId. The service finds the caller’s Coach row by externalUserId. If none exists it falls back to an active coach whose email matches the x-user-email request header. It then looks up that coach id in settings.smartsend.userMap. Response when the studio is not connected:

{ "ok": true, "data": { "connected": false }, "requestId": "req_123" }

Response when connected:

{
  "ok": true,
  "data": {
    "connected": true,
    "apiKey": "YOUR_SMARTSEND_ORG_KEY",
    "orgSlug": "my-studio",
    "coachId": "cmaq1c8v20003abcd1234efgh",
    "coachName": "Dana Levi",
    "user": { "id": "u_101", "name": "Dana Levi" },
    "userMap": {
      "cmaq1c8v20003abcd1234efgh": { "id": "u_101", "name": "Dana Levi" }
    }
  },
  "requestId": "req_123"
}

orgSlug, coachId, coachName and user are null when unknown. userMap is the whole stored map.

This response contains the studio’s SmartSend organization key in apiKey. Treat the response as a secret and never log it.

Errors: UNAUTHORIZED (401) when the auth context is incomplete.

`PUT /v1/web/whatsapp/smartsend/org-slug`

Also PUT /v1/whatsapp/smartsend/org-slug. Sets or clears the studio’s slug inside SmartSend. The web app builds deep links to conversations from it. Auth: web lane or bearer lane, any role.

string | null

required

Trimmed, at most 64 characters, only letters, digits, dot, dash or underscore. null or an empty string removes the stored slug.

Response: 200.

{ "ok": true, "data": { "orgSlug": "my-studio" }, "requestId": "req_123" }

Errors: VALIDATION (422), NOT_FOUND (404) studio not found.

`PUT /v1/web/whatsapp/smartsend/user-map`

Also PUT /v1/whatsapp/smartsend/user-map. Maps Perform coaches to SmartSend users. Auth: web lane or bearer lane, any role.

object

required

Keys are Coach.id values. Each value is either { "id": string, "name": string } (name at most 160 characters) or null.

The sent map is merged over the stored one. A null value removes that coach’s entry. Coaches not mentioned keep their mapping. Coach ids are not checked against the studio.

{
  "map": {
    "cmaq1c8v20003abcd1234efgh": { "id": "u_101", "name": "Dana Levi" },
    "cmaq1c8v20009abcd1234efgh": null
  }
}

Response: 200 with the full map after the merge.

{
  "ok": true,
  "data": {
    "userMap": {
      "cmaq1c8v20003abcd1234efgh": { "id": "u_101", "name": "Dana Levi" }
    }
  },
  "requestId": "req_123"
}

Errors: VALIDATION (422), NOT_FOUND (404) studio not found.

Mailing lists

`POST /v1/web/whatsapp/smartsend/lists`

Also POST /v1/whatsapp/smartsend/lists. Creates a SmartSend mailing list from selected trainees. Auth: web lane or bearer lane, any role.

string

required

Trimmed, 1 to 120 characters.

string[]

required

1 to 1000 client ids.

What the service does:

De-duplicates clientIds and loads the matching clients in the caller’s studio.
Skips clients with no phone. Collapses clients that share a phone (compared by digits only) into one contact.
Throws when no contact is left.
Calls smartsend.createMailingList. The client creates the list with POST /lists, then adds each recipient with its own POST /lists/:id/recipients call, five at a time. A recipient SmartSend rejects is skipped. If every recipient is rejected the client deletes the list and throws.

The client uses SmartSend’s root /lists API on purpose. Lists written through /integrations/make/lists/create land in a store the SmartSend web app cannot read. Response: 201. total is the number of distinct requested ids. added is what SmartSend accepted. skipped is total - added, so it covers missing phones, duplicates, ids from other studios and SmartSend rejections together.

{
  "ok": true,
  "data": {
    "id": "lst_8f2c",
    "name": "October challenge",
    "total": 40,
    "added": 37,
    "skipped": 3
  },
  "requestId": "req_123"
}

Errors:

Code	Status	When
`VALIDATION`	422	Body fails the schema
`BAD_REQUEST`	400	Studio not connected, or `none of the selected trainees has a phone number`
`CONFLICT`	409	SmartSend reports that a list with this name already exists
`INTERNAL`	500	Any other SmartSend failure, including every recipient being rejected

Inbound webhook

`POST /v1/whatsapp/webhook/:studioId`

Receives inbound WhatsApp messages from SmartSend for one studio. Auth: no lane middleware. The controller reads the token query parameter and passes it to smartsend.verifyWebhookToken, which compares it to SMARTSEND_WEBHOOK_SECRET with timingSafeEqual. A missing token, an unset secret or a length mismatch all fail. The global /v1 rate limiter still applies.

string

required

The internal Studio.id. This is the id used in the hook URL built by the connect endpoint.

string

required

Must equal SMARTSEND_WEBHOOK_SECRET.

Body: one message object or an array of them. parseInbound keeps only items where senderId and text are strings.

Field	Type	Use
`text`	string	Message text. Required
`senderId`	string	WhatsApp id. Required. A trailing `@c.us` or `@g.us` is stripped to get the phone
`senderName`	string	Optional. Defaults to an empty string
`isGroupMessage`	boolean	Messages with `true` are skipped
`type`	string	Optional. Defaults to `chat`
`isMyContact`	boolean	Optional
`time`	number	Optional. Stored as `timestamp`, `0` when absent

For each non-group message the service:

Looks for a client in the studio whose phone equals the parsed phone exactly.
Creates a WhatsappMessage row with direction: "INBOUND", status: "DELIVERED", the text as body, the parsed message as payload, and clientId when a client matched.
When a client matched, creates an InboxItem with type: "MESSAGE", refId set to the message id and priority: 1.

A message from an unknown number is still stored, with no client and no inbox item. Response: 200. received counts the stored messages.

{ "ok": true, "data": { "received": 1 }, "requestId": "req_123" }

Errors:

Code	Status	When
`UNAUTHORIZED`	401	`invalid webhook token`
`VALIDATION`	422	`studioId` path parameter is empty

The service does not check that studioId exists before inserting. An unknown id fails the foreign key and the shared error mapper turns that into CONFLICT (409).

WhatsApp AI agent uses the same webhook token scheme on a separate SmartSend organization.
Coach assistant can send a WhatsApp message with the studio’s key after the coach confirms a proposal.
Automation covers automated sends.

API basics

Trainees

Plans and libraries

Tracking

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

Mounting and auth

Where the SmartSend settings live

Sending

`POST /v1/web/whatsapp/send`

`POST /v1/web/whatsapp/bulk`

Message history

`GET /v1/web/whatsapp/messages`

`GET /v1/web/whatsapp/chat`

Templates

`GET /v1/web/whatsapp/templates`

`POST /v1/web/whatsapp/templates`

`GET /v1/web/whatsapp/templates/:id`

`PATCH /v1/web/whatsapp/templates/:id`

`DELETE /v1/web/whatsapp/templates/:id`

Connecting SmartSend

`POST /v1/web/whatsapp/connect`

`GET /v1/web/whatsapp/smartsend/users`

`GET /v1/web/whatsapp/smartsend/chat-embed`

`PUT /v1/web/whatsapp/smartsend/org-slug`

`PUT /v1/web/whatsapp/smartsend/user-map`

Mailing lists

`POST /v1/web/whatsapp/smartsend/lists`

Inbound webhook

`POST /v1/whatsapp/webhook/:studioId`

​Mounting and auth

​Where the SmartSend settings live

​Sending

​POST /v1/web/whatsapp/send

​POST /v1/web/whatsapp/bulk

​Message history

​GET /v1/web/whatsapp/messages

​GET /v1/web/whatsapp/chat

​Templates

​GET /v1/web/whatsapp/templates

​POST /v1/web/whatsapp/templates

​GET /v1/web/whatsapp/templates/:id

​PATCH /v1/web/whatsapp/templates/:id

​DELETE /v1/web/whatsapp/templates/:id

​Connecting SmartSend

​POST /v1/web/whatsapp/connect

​GET /v1/web/whatsapp/smartsend/users

​GET /v1/web/whatsapp/smartsend/chat-embed

​PUT /v1/web/whatsapp/smartsend/org-slug

​PUT /v1/web/whatsapp/smartsend/user-map

​Mailing lists

​POST /v1/web/whatsapp/smartsend/lists

​Inbound webhook

​POST /v1/whatsapp/webhook/:studioId

​Related pages

Mounting and auth

Where the SmartSend settings live

Sending

`POST /v1/web/whatsapp/send`

`POST /v1/web/whatsapp/bulk`

Message history

`GET /v1/web/whatsapp/messages`

`GET /v1/web/whatsapp/chat`

Templates

`GET /v1/web/whatsapp/templates`

`POST /v1/web/whatsapp/templates`

`GET /v1/web/whatsapp/templates/:id`

`PATCH /v1/web/whatsapp/templates/:id`

`DELETE /v1/web/whatsapp/templates/:id`

Connecting SmartSend

`POST /v1/web/whatsapp/connect`

`GET /v1/web/whatsapp/smartsend/users`

`GET /v1/web/whatsapp/smartsend/chat-embed`

`PUT /v1/web/whatsapp/smartsend/org-slug`

`PUT /v1/web/whatsapp/smartsend/user-map`

Mailing lists

`POST /v1/web/whatsapp/smartsend/lists`

Inbound webhook

`POST /v1/whatsapp/webhook/:studioId`

Related pages