# Configure SMS fallback (v1)

Configures SMS fallback for the given client. When enabled, an SMS is sent automatically if the recipient is not on WhatsApp or WhatsApp delivery fails.
The gateway password is write-only: it is never returned by any endpoint, so leave smsPassword out (or blank) to keep the stored one, and supply it only to change it.

Endpoint: PUT /payless4messaging-service/WhatsApp/api/v1/clients/{clientRef}/sms-fallback
Version: 3.0.0
Security: apikeyAuth

## Path parameters:

  - `clientRef` (string, required)
    The client reference to configure.
    Example: "Growthpoint"

## Request fields (application/json):

  - `smsMode` (string)
    disabled, fallback, or direct.
    Example: "fallback"

  - `smsFallback` (boolean)
    Example: true

  - `smsUserId` (string)
    Example: "support@ecommunicate.co.za"

  - `smsPassword` (string)
    Write-only. Omit or leave blank to keep the stored password; supply a value only to change it.
    Example: "********"

  - `smsClientRef` (string)
    Example: "ecomtest1"

## Response 200 fields (application/json):

  - `id` (string)
    Example: "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890"

  - `clientRef` (string)
    Groups your records under a business entity. Can be renamed by an administrator, so treat it as a label rather than a durable key.
    Example: "Growthpoint"

  - `displayName` (string)
    Trading name shown to your own customers. Falls back to the client reference when unset.
    Example: "Growthpoint Therapies Inc"

  - `accountType` (string)
    Example: "Prepaid"

  - `pricingModel` (string)
    Example: "META_PMP"

  - `clientWhatsAppBalance` (number)
    Example: 16112.95

  - `userInitiatedConversationBalance` (number)
    Example: 20

  - `businessInitiatedConversationBalance` (number)
    Example: 20

  - `clientSMSBalance` (number)
    Example: 50.34

  - `primaryEmailAddress` (string)
    Example: "ops@example.com"

  - `secondaryEmailAddress` (string)
    Example: "finance@example.com"

  - `clientEmailAddress` (string)
    Example: "support@acme.example"

  - `upperNotificationLimit` (number)
    Example: 1000

  - `lowerNotificationLimit` (number)
    Example: 100

  - `countryCode` (string)
    Example: "ZA"

  - `countryTimezone` (string)
    Example: "Africa/Johannesburg"

  - `parentClientRef` (string)
    The parent's client reference, or absent for a top-level client.
    Example: "Growthpoint"

  - `reseller` (boolean)

  - `useParentNumber` (boolean)

  - `useParentCredit` (boolean)

  - `popiaComplianceEnabled` (boolean)
    Example: true

  - `eligible1000Free` (boolean)

  - `splitConversation` (boolean)

  - `useApi` (boolean)
    Example: true

  - `monthlyFundAllocation` (boolean)

  - `monthlyBusinessInitiatedBalanceAllocation` (integer)

  - `monthlyUserInitiatedBalanceAllocation` (integer)

  - `smsMode` (string)
    Example: "fallback"

  - `smsFallback` (boolean)
    Example: true

  - `smsUserId` (string)
    The SMS gateway username. The password is never returned.
    Example: "support@ecommunicate.co.za"

  - `smsClientRef` (string)
    Example: "ecomtest1"

  - `license` (object)
    Licence counts recorded against the client.

  - `license.totalLicenseAllocated` (integer)
    Example: 10

  - `license.licensesUnallocated` (integer)
    Example: 4

  - `license.licensesUsed` (integer)
    Example: 6

## Response 401 fields (application/json):

  - `status` (string)
    Example: "ERROR"

  - `message` (string)
    Example: "Unauthorized user"

  - `requestId` (string)
    Example: "c3a1f8e2-4b6d-11ee-be56-0242ac120002"

  - `timestamp` (string)
    Example: "2026-01-15T10:30:00Z"

## Response 404 fields (application/json):

  - `status` (string)
    Example: "ERROR"

  - `message` (string)
    Example: "Resource not found"

  - `requestId` (string)
    Example: "c3a1f8e2-4b6d-11ee-be56-0242ac120002"

  - `timestamp` (string)
    Example: "2026-01-15T10:30:00Z"