API Docs

Channel API for WhatsApp line health.

Use the EZW Channel API to check one WhatsApp line at a time with a line-scoped bearer token. Workspace endpoints support token rotation, owner control, inbox operations, and admin setup.

View v1 reference Request access

Current API status

Line-scoped health first, workspace control around it.

The current public contract is the Channel API v1 health endpoint. Owners and admins create or rotate a token from a line in the workspace, then integrations call the v1 endpoint with that line token.

Channel base URLhttps://app.ezw.solutions/api/v1

Channel authAuthorization: Bearer {lineApiToken}

Token scopeOne token, one WhatsApp line

HealthGET /health

Channel API v1 is line-scoped. One line API token resolves to one WhatsApp line.
Health responses preserve EZW line truth: lifecycleState, effectiveSendState, and sendable.
Workspace/admin endpoints use a workspace user bearer token to create or rotate line API tokens.
Built for support inbox workflows, not campaign blasts or cold outbound messaging.

Quick start

Create a line token, then check channel health.

1. Rotate token

Owners and admins create or rotate a line token from the selected WhatsApp line.

curl -X POST https://app.ezw.solutions/api/lines/{lineId}/api-token \
  -H "Authorization: Bearer {idToken}"

2. Check health

Call the v1 health endpoint with the line API token. Use wakeup=false for a read-only check.

curl -X GET 'https://app.ezw.solutions/api/v1/health?wakeup=false&channel_type=web' \
  -H "Authorization: Bearer {lineApiToken}"

3. Preserve line truth

Use both the channel status and EZW line states instead of flattening health to connected/disconnected.

{
  "health": {
    "status": {
      "code": 4,
      "text": "AUTH"
    }
  },
  "line": {
    "lifecycleState": "connected",
    "effectiveSendState": "sendable",
    "sendable": true
  }
}

Operation reference

Channel API v1 and supporting workspace operations.

The first operation is the public line-scoped API. Token creation and broader workspace routes use a workspace user bearer token and exist to control who can issue access for each line.

Channel API v1

Check channel health

Check the WhatsApp line attached to the bearer token and optionally request a safe wakeup.

GEThttps://app.ezw.solutions/api/v1/health

Auth: Line API bearer token created from the owner/admin workspace.
Content type: application/json
Status: Line-scoped read

Parameters

Name	In	Type	Required	Details
`Authorization`	header	Bearer token	Required	Use Authorization: Bearer {lineApiToken}. Tokens start with ezw_line_ and resolve to one line.
`wakeup`	query	boolean	Optional	true by default. Use false for a read-only health check.
`channel_type`	query	web \| mobile	Optional	Defaults to web. Used to identify the client surface making the check.
`platform`	query	string	Optional	Client platform label, for example Desktop,Mac OS,15.0.

Responses

200

Health returned for the token's line. A wakeup command can be included when requested.

400

wakeup is not true/false or channel_type is not web/mobile.

401

Line API token is missing, invalid, revoked, or detached from an active line.

501

PostgreSQL source of truth is not configured.

Notes

Status text follows the channel model: AUTH, QR, LAUNCH, INIT, STOP, or ERROR.
EZW also returns lifecycleState and effectiveSendState so clients do not flatten operational truth.
When wakeup=true and the line has no active worker assignment, EZW queues a system wakeup command.

ShellExample

Request

curl -X GET 'https://app.ezw.solutions/api/v1/health?wakeup=false&channel_type=web' \
  -H "Authorization: Bearer {lineApiToken}"

Response

{
  "channelId": "line_123",
  "channelType": "web",
  "wakeupRequested": false,
  "health": {
    "startAt": 1778140800,
    "uptime": 3600,
    "status": {
      "code": 4,
      "text": "AUTH"
    }
  },
  "line": {
    "displayName": "Support",
    "phoneNumber": "+972501112222",
    "lifecycleState": "connected",
    "effectiveSendState": "sendable",
    "sendable": true
  }
}

Channel API access

Read active line API token metadata

Read whether a line already has an active Channel API token and when it was last used.

GEThttps://app.ezw.solutions/api/lines/{lineId}/api-token

Auth: Workspace user bearer token with line management permission.
Content type: application/json
Status: Admin read

Parameters

Name	In	Type	Required	Details
`Authorization`	header	Bearer token	Required	Use Authorization: Bearer {idToken} from workspace login.
`lineId`	path	string	Required	Existing line id in the authenticated organization.

Responses

200

Token metadata returned. token can be null when no active token exists.

403

Active organization membership with line management permission is required.

404

Line was not found in the authenticated organization.

501

PostgreSQL source of truth is not configured.

Notes

The plaintext token is not returned by this read endpoint.
Use tokenPreview only for identifying which token is active in the owner dashboard.

ShellExample

Request

curl https://app.ezw.solutions/api/lines/{lineId}/api-token \
  -H "Authorization: Bearer {idToken}"

Response

{
  "lineId": "line_123",
  "token": {
    "id": "token_123",
    "lineId": "line_123",
    "tokenPreview": "ezw_line_MDEy...dXY",
    "createdAt": "2026-05-07T09:00:00.000Z",
    "lastUsedAt": "2026-05-07T09:10:00.000Z"
  }
}

Channel API access

Create or rotate a line API token

Create a new line-scoped bearer token and revoke any previous active token for that line.

POSThttps://app.ezw.solutions/api/lines/{lineId}/api-token

Auth: Workspace user bearer token with line management permission.
Content type: application/json
Status: Admin write

Parameters

Name	In	Type	Required	Details
`Authorization`	header	Bearer token	Required	Use Authorization: Bearer {idToken} from workspace login.
`lineId`	path	string	Required	Existing line id in the authenticated organization.

Responses

201

Token rotated. Copy lineApiToken from this response; it is shown on creation/rotation.

403

Active organization membership with line management permission is required.

404

Line was not found in the authenticated organization.

501

PostgreSQL source of truth is not configured.

Notes

A rotated token is scoped to one line and does not grant access to other lines.
The owner dashboard exposes this same create/rotate flow from the selected line.

ShellExample

Request

curl -X POST https://app.ezw.solutions/api/lines/{lineId}/api-token \
  -H "Authorization: Bearer {idToken}"

Response

{
  "status": "line_api_token_rotated",
  "lineId": "line_123",
  "token": {
    "id": "token_123",
    "lineId": "line_123",
    "tokenPreview": "ezw_line_MDEy...dXY",
    "createdAt": "2026-05-07T09:00:00.000Z"
  },
  "lineApiToken": "ezw_line_MDEyMzQ1Njc4OWFiY2Rl..."
}

Authentication

Sign in to a workspace

Exchange a workspace email and password for an ID token used by the customer workspace API.

POSThttps://app.ezw.solutions/api/auth/login

Auth: No bearer token. Uses the workspace user's email and password.
Content type: application/json
Status: Customer workspace

Parameters

Name	In	Type	Required	Details
`email`	body	string	Required	Workspace user email address.
`password`	body	string	Required	Workspace password. Omit only when completing a new-password challenge.
`session`	body	string	Optional	Cognito challenge session returned by a previous login attempt.
`newPassword`	body	string	Optional	Required only when session is present for NEW_PASSWORD_REQUIRED.

Responses

200

Authenticated. Use idToken as the bearer token.

400

Email and password, or challenge session and new password, are missing.

409

A Cognito challenge must be completed before sign-in succeeds.

503

Cognito login is not configured for the deployment.

Notes

The ID token carries workspace identity and role claims.
Use workspace tokens for admin/workspace endpoints; use line API tokens for Channel API v1 endpoints.

ShellExample

Request

curl -X POST https://app.ezw.solutions/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@example.com",
    "password": "your-password"
  }'

Response

{
  "authenticated": true,
  "idToken": "{idToken}",
  "refreshToken": "{refreshToken}",
  "tokenType": "Bearer",
  "expiresInSeconds": 3600,
  "expiresAt": "2026-05-07T09:00:00.000Z"
}

WhatsApp lines

List visible WhatsApp lines

Return WhatsApp lines visible to the authenticated operator, including lifecycle and sendability state.

GEThttps://app.ezw.solutions/api/lines

Auth: Bearer token for a workspace user.
Content type: application/json
Status: Source-of-truth read

Parameters

Name	In	Type	Required	Details
`Authorization`	header	Bearer token	Required	Use Authorization: Bearer {idToken}.
`limit`	query	integer	Optional	Positive integer limiting the number of returned lines.
`lineId`	query	string	Optional	Restrict the result to one line visible to the caller.

Responses

200

Visible lines returned for the caller.

400

limit is present but not a positive integer.

403

The authenticated actor cannot list workspace lines.

501

PostgreSQL source of truth is not configured.

Notes

Line visibility is scoped by organization, role, and explicit line permissions.
Redis is never the source of truth for line state.

ShellExample

Request

curl https://app.ezw.solutions/api/lines?limit=10 \
  -H "Authorization: Bearer {idToken}"

Response

{
  "lines": [
    {
      "id": "line_123",
      "displayName": "Sales",
      "lifecycleState": "connected",
      "effectiveSendState": "sendable"
    }
  ]
}

WhatsApp lines

Request a fresh QR pairing command

Queue a QR pairing command for an existing line when the workspace and actor are eligible.

POSThttps://app.ezw.solutions/api/lines/{lineId}/qr

Auth: Bearer token for an owner or admin workspace user.
Content type: application/json
Status: Line command

Parameters

Name	In	Type	Required	Details
`Authorization`	header	Bearer token	Required	Use Authorization: Bearer {idToken}.
`lineId`	path	string	Required	Existing line id in the authenticated organization.
`idempotencyKey`	body	string	Optional	Caller supplied command id for retry-safe QR requests.

Responses

200

QR command accepted or already represented by the idempotency key.

403

Actor, billing, line slot, or email verification rule blocks QR pairing.

404

The line does not exist in the authenticated organization.

Notes

The API returns command state. Read the QR image separately when it is available.
QR pairing is for linking existing WhatsApp numbers to the support inbox workflow.

ShellExample

Request

curl -X POST https://app.ezw.solutions/api/lines/{lineId}/qr \
  -H "Authorization: Bearer {idToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "qr-setup-001"
  }'

Response

{
  "lineId": "line_123",
  "status": "qr_requested",
  "command": {
    "id": "qr-setup-001",
    "queued": true
  },
  "expiresInSeconds": 60
}

WhatsApp lines

Read the current pairing QR image

Return the current short-lived QR image data URL for an owner or admin when a QR is available.

GEThttps://app.ezw.solutions/api/lines/{lineId}/qr

Auth: Bearer token for an owner or admin workspace user.
Content type: application/json
Status: Short-lived read

Parameters

Name	In	Type	Required	Details
`Authorization`	header	Bearer token	Required	Use Authorization: Bearer {idToken}.
`lineId`	path	string	Required	Existing line id in the authenticated organization.

Responses

200

Current pairing QR returned with no-store cache headers.

403

Only owners/admins with verified email can view QR codes.

404

No current QR is available or the line is not visible.

503

The transient QR store is unavailable.

Notes

The raw QR secret is never returned; the response contains a QR image data URL.
Clients should refresh until a QR is available, then stop once it expires or pairing succeeds.

ShellExample

Request

curl https://app.ezw.solutions/api/lines/{lineId}/qr \
  -H "Authorization: Bearer {idToken}"

Response

{
  "lineId": "line_123",
  "qrImageDataUrl": "data:image/png;base64,...",
  "qrExpiresAt": "2026-05-07T09:01:00.000Z",
  "observedAt": "2026-05-07T09:00:10.000Z",
  "sessionRunId": "run_123",
  "fencingToken": 42
}

Inbox conversations

List inbox conversations

Return conversations visible to the authenticated operator, optionally filtered by line.

GEThttps://app.ezw.solutions/api/conversations

Auth: Bearer token for a workspace user.
Content type: application/json
Status: Inbox read

Parameters

Name	In	Type	Required	Details
`Authorization`	header	Bearer token	Required	Use Authorization: Bearer {idToken}.
`limit`	query	integer	Optional	Positive integer limiting the number of returned conversations.
`lineId`	query	string	Optional	Return conversations for one visible WhatsApp line.

Responses

200

Conversation summaries returned for the authenticated actor.

400

limit is present but not a positive integer.

403

The authenticated actor cannot list inbox conversations.

501

PostgreSQL source of truth is not configured.

Notes

Conversation data is organization-scoped and permission-filtered.
Use each conversation version when claiming or assigning work.

ShellExample

Request

curl "https://app.ezw.solutions/api/conversations?lineId={lineId}&limit=25" \
  -H "Authorization: Bearer {idToken}"

Response

{
  "conversations": [
    {
      "id": "conversation_123",
      "lineId": "line_123",
      "customerDisplayName": "Customer",
      "ownerUserId": "user_123",
      "state": "open",
      "version": 7
    }
  ]
}

Inbox conversations

Assign a conversation

Assign a conversation to a team member with optimistic conflict protection.

POSThttps://app.ezw.solutions/api/conversations/{conversationId}/assign

Auth: Bearer token for a workspace user allowed to assign the conversation.
Content type: application/json
Status: Versioned write

Parameters

Name	In	Type	Required	Details
`Authorization`	header	Bearer token	Required	Use Authorization: Bearer {idToken}.
`conversationId`	path	string	Required	Existing conversation id visible in the authenticated organization.
`targetUserId`	body	string	Required	Workspace user who should own the conversation.
`expectedVersion`	body	integer	Required	Current conversation version from the latest read.

Responses

200

Conversation assignment was updated.

400

expectedVersion or targetUserId is invalid.

403

Actor or target user is not allowed for the conversation.

404

Conversation was not found in the organization.

409

Conversation version changed before the assignment was applied.

501

PostgreSQL source of truth is not configured.

Notes

expectedVersion prevents two operators from silently overwriting each other.
Assignment changes publish a live update so connected clients can refetch.

ShellExample

Request

curl -X POST https://app.ezw.solutions/api/conversations/{conversationId}/assign \
  -H "Authorization: Bearer {idToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUserId": "user_123",
    "expectedVersion": 7
  }'

Response

{
  "assignment": {
    "conversationId": "conversation_123",
    "lineId": "line_123",
    "state": "open",
    "ownerUserId": "user_123",
    "version": 8,
    "updatedByUserId": "user_owner"
  }
}

Outbound replies

Queue an outbound reply

Queue a text reply or one image attachment from a connected line to an existing conversation or direct recipient.

POSThttps://app.ezw.solutions/api/lines/{lineId}/send

Auth: Bearer token for a workspace user allowed to send from the line.
Content type: application/json or multipart/form-data
Status: Idempotent write

Parameters

Name	In	Type	Required	Details
`Authorization`	header	Bearer token	Required	Use Authorization: Bearer {idToken}.
`Idempotency-Key`	header	string	Required	Required for outbound sends. A body idempotencyKey is also accepted.
`lineId`	path	string	Required	Line that should send the reply.
`conversationId`	body/form	string	One of	Existing conversation target. Do not combine with recipientPhoneNumber.
`recipientPhoneNumber`	body/form	string	One of	Direct recipient target. Do not use for cold outbound lists.
`bodyText`	body/form	string	One of	Text body. Required unless media is present.
`media`	form	File	Optional	Image attachment only, up to 25 MB.

Responses

202

Reply was queued or the idempotent attempt already exists.

400

Missing idempotency key, target, content, or valid media.

403

Actor cannot send from the requested line.

404

Conversation, actor, line, or target is not visible.

409

Line is not currently sendable.

501

Media bucket or PostgreSQL source of truth is not configured.

Notes

The API queues replies; provider delivery status is reconciled asynchronously.
This endpoint is for support replies and controlled direct customer follow-up, not campaign broadcasts.

ShellExample

Request

curl -X POST https://app.ezw.solutions/api/lines/{lineId}/send \
  -H "Authorization: Bearer {idToken}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-2026-05-07-001" \
  -d '{
    "conversationId": "conversation_123",
    "bodyText": "Thanks, I am checking this now."
  }'

Response

{
  "conversationId": "conversation_123",
  "outboundAttempt": {
    "id": "attempt_123",
    "lineId": "line_123",
    "status": "queued",
    "idempotencyKey": "send-2026-05-07-001",
    "inserted": true
  },
  "outboundMessage": {
    "id": "message_123",
    "inserted": true
  }
}

Media access

Create a signed media URL

Create a short-lived signed URL for archived inbound or outbound media visible to the caller.

GEThttps://app.ezw.solutions/api/attachments/{attachmentId}/url

Auth: Bearer token for a workspace user allowed to view the related conversation.
Content type: application/json
Status: Short-lived read

Parameters

Name	In	Type	Required	Details
`Authorization`	header	Bearer token	Required	Use Authorization: Bearer {idToken}.
`attachmentId`	path	string	Required	Archived attachment id.
`expiresInSeconds`	query	integer	Optional	URL lifetime from 1 to 3600 seconds. Defaults to 300.

Responses

200

Signed URL returned and media view recorded.

400

expiresInSeconds is outside the allowed range.

403

Actor cannot view the related media.

404

Attachment is not visible in the authenticated organization.

501

Database or media bucket is not configured.

Notes

Signed URLs are short-lived and do not expose storage credentials.
Media reads are recorded for organization auditability.

ShellExample

Request

curl "https://app.ezw.solutions/api/attachments/{attachmentId}/url?expiresInSeconds=300" \
  -H "Authorization: Bearer {idToken}"

Response

{
  "attachment": {
    "id": "attachment_123",
    "lineId": "line_123",
    "messageId": "message_123",
    "conversationId": "conversation_123",
    "contentType": "image/jpeg",
    "mediaKind": "image",
    "archiveStatus": "archived"
  },
  "signedUrl": "https://..."
}

Live updates

Subscribe to workspace updates

Open an authenticated Server-Sent Events stream for workspace refresh hints.

GEThttps://app.ezw.solutions/api/live/stream

Auth: Bearer token for a workspace user.
Content type: text/event-stream
Status: Streaming read

Parameters

Name	In	Type	Required	Details
`Authorization`	header	Bearer token	Required	Use Authorization: Bearer {idToken}.

Responses

200

SSE stream opened.

401

Bearer token is missing or invalid.

501

Redis live-update configuration is missing.

500

Redis live-update configuration is invalid or unavailable.

Notes

Events are refresh hints. Clients should refetch the source endpoint after receiving an event.
The stream is organization-scoped and does not carry cross-tenant data.

ShellExample

Request

curl -N https://app.ezw.solutions/api/live/stream \
  -H "Authorization: Bearer {idToken}" \
  -H "Accept: text/event-stream"

Response

event: conversation.assignment_updated
data: {"organizationId":"org_123","payload":{"conversationId":"conversation_123"}}

event: conversation.outbound_queued
data: {"organizationId":"org_123","payload":{"lineId":"line_123"}}

Endpoint catalog

Current app and Channel API endpoints.

Channel API endpoints use a line API token. Workspace endpoints require an organization principal and are scoped by organization, actor role, line visibility, and conversation assignment rules.

Channel API v1

Line-scoped bearer-token endpoints for WhatsApp channel health.

GET/api/v1/health

Check one line's health and optionally request a safe wakeup.

GET/api/lines/{lineId}/api-token

Read active line API token metadata from the owner/admin workspace.

POST/api/lines/{lineId}/api-token

Create or rotate the line-scoped Channel API bearer token.

Authentication

POST/api/auth/login

Exchange workspace email and password for an ID token.

POST/api/auth/refresh

Exchange a refresh token for a fresh ID token.

GET/api/auth/session

Validate the bearer token and return the authenticated principal.

Workspace onboarding

Create the first organization record before billing and line setup.

POST/api/signup/organization

Create an organization, owner user, pending billing state, and allocated line slots.

WhatsApp lines

Create, connect, inspect, assign, restrict, and archive WhatsApp numbers.

GET/api/lines

List visible WhatsApp lines with lifecycle and sendability state.

POST/api/lines

Create a line and queue QR pairing for the new number.

POST/api/lines/{lineId}/qr

Request a fresh QR pairing command for an existing line.

GET/api/lines/{lineId}/qr

Read the current short-lived QR image data URL when one is available.

PUT/api/lines/{lineId}/assignment

Set or clear the default assignee for conversations on a line.

GET/api/lines/{lineId}/permissions

List explicit staff permissions for one line.

PUT/api/lines/{lineId}/permissions/{targetUserId}

Set whether a staff member can view and send from a line.

DELETE/api/lines/{lineId}/permissions/{targetUserId}

Clear explicit permissions back to the workspace default.

POST/api/lines/{lineId}/archive

Archive a line and stop it from being used for new work.

Inbox conversations

Read conversations, claim ownership, assign staff, edit contact names, and add internal notes.

GET/api/conversations

List conversations visible to the authenticated operator.

GET/api/conversations/{conversationId}/messages

Read the timeline for one conversation.

POST/api/conversations/{conversationId}/claim

Claim an unassigned conversation using expectedVersion conflict protection.

POST/api/conversations/{conversationId}/assign

Assign a conversation to another staff member using expectedVersion conflict protection.

PATCH/api/conversations/{conversationId}/contact

Update the internal display name for a customer contact.

GET/api/conversations/{conversationId}/notes

List internal-only notes for a conversation.

POST/api/conversations/{conversationId}/notes

Create an internal-only note that is never sent to WhatsApp.

Outbound replies

Queue operator replies from a connected line with durable idempotency.

POST/api/lines/{lineId}/send

Queue a text reply or one image attachment to an existing conversation or direct recipient.

Media access

Fetch signed URLs for archived customer media without exposing storage credentials.

GET/api/attachments/{attachmentId}/url

Create a short-lived signed media URL, with expiresInSeconds from 1 to 3600.

Team administration

Invite staff, update roles, disable users, and inspect access history.

GET/api/memberships

List active and invited workspace members.

POST/api/memberships

Invite a staff member with a supported organization role.

PATCH/api/memberships/{targetUserId}

Change a member role.

DELETE/api/memberships/{targetUserId}

Disable a member.

GET/api/audit-logs

Read organization audit events, optionally filtered by eventType.

Billing and live updates

Read billing state, start recovery checkout, and subscribe to workspace changes.

GET/api/billing/status

Read current billing state, policy, line slots, and seat counts.

POST/api/billing/recovery/checkout

Create a billing recovery checkout session when the workspace is restricted.

GET/api/live/stream

Open an authenticated Server-Sent Events stream for workspace updates.

Request rules

Operational guarantees and limits.

Line token scope

A Channel API token belongs to one WhatsApp line. Rotating a token revokes the previous active token for that same line.

Health wakeup

GET /api/v1/health defaults to wakeup=true. Use wakeup=false when the client only wants to inspect state.

Workspace guardrails

Token reads and rotations require a workspace user with line management permission. Line and role permissions still apply in the owner dashboard.

Support-inbox boundary

The API is for line health and controlled support workflows. It does not expose campaign broadcasts, cold outbound lists, or chatbot-first automation.

Errors

Common response statuses.

400

Invalid request body, query value, idempotency key, or send target.

401

Missing, expired, invalid, or unconfigured workspace token or line API token.

403

Authenticated user does not have the required workspace, role, or line permission.

404

The scoped organization resource was not found or is not visible to the caller.

409

Conflict, duplicate setup, stale expectedVersion, or non-sendable line state.

501

The deployment is missing a required source-of-truth service for that endpoint.

v1 boundary

EZW Channel API v1 currently exposes line-scoped health. Workspace endpoints manage token access and the support inbox control layer. Bulk/campaign tooling is outside this API boundary.

Request integration access