Preview SMS Cost (v1)

Method & Path

POST /api/v1/workspace/:workspaceId/sms/preview-cost

Description

Previews the deduped recipient count, invalid recipients, segments per message, and total cost before sending.

Authentication

Required: Workspace auth.

Persona Access:

• Workspace Owner: Allowed
• Staff (role-based): Requires sms.send
• Customer(client): Not allowed

Headers

• Authorization: Bearer <workspaceToken>
• Content-Type: application/json
• X-Staff-Id: <staffId> (optional; required when acting as Staff)

Path Parameters

Name	Type	Required	Description
workspaceId	string	Yes	Workspace ID

Request Body

{
  "text": "مرحبا 👋",
  "recipients": {
    "mobiles": ["+970599000000", "+972590000000"],
    "clientIds": ["66f0..."],
    "referralIds": ["66f1..."],
    "groupIds": ["66f2..."]
  }
}

Response 200 OK

{
  "charsPerSegment": 150,
  "costPerSegment": 0.02,
  "segmentsPerMessage": 1,
  "dedupedRecipientsCount": 12,
  "invalidRecipients": ["+123..."],
  "totalCost": 0.24
}

Common Errors

• 400 Bad Request: Invalid workspaceId
• 401 Unauthorized: Missing/invalid workspace token
• 403 Forbidden: Staff missing sms.send
• 422 Unprocessable Entity: Validation failed
• 500 Internal Server Error: Unexpected error