Send and track messages

Send messages with a server-side API key. Each new message needs an Idempotency-Key header. Start with the quickstart for a complete request, and use the API Reference for field constraints.

Choose a format

WhatsApp supports text, images, buttons, and single-select lists. SMS supports text only.

Text

{
  "channel_type": "whatsapp",
  "to": "+23276123456",
  "text": "Your appointment is confirmed."
}

Images

Use a direct public JPEG or PNG URL, up to 5 MiB. Put the caption inside image rather than the top-level text field. Private addresses and redirects are blocked; base64 and local file paths are not supported.

{
  "channel_type": "whatsapp",
  "to": "+23276123456",
  "image": {
    "url": "https://example.com/order.jpg",
    "caption": "Your order is ready."
  }
}

The URL above is illustrative; replace it with a real image URL. Ziph does not store the image.

Buttons

Use buttons for a few direct choices or actions. Add up to three buttons to a WhatsApp text or image message. Quick-reply buttons return a selection; URL, copy, and call buttons perform their named action without generating click webhooks.

{
  "channel_type": "whatsapp",
  "to": "+23276123456",
  "text": "Can you confirm your appointment?",
  "buttons": [
    { "id": "confirm", "title": "Confirm" },
    { "id": "cancel", "title": "Cancel" }
  ]
}

The quick-reply example above returns the selected button’s id and title in message.button_reply through inbound webhooks.

Lists

Use a single-select list to group choices into a menu. The recipient taps the label in button_text to open the list, then selects one row. This menu opener is part of list, not a separate entry in buttons.

Include a WhatsApp text message and a list object with titled sections and rows. Lists support up to ten rows in total across one to ten sections; every section needs at least one row. A list cannot be combined with images or buttons.

{
  "channel_type": "whatsapp",
  "to": "+23276123456",
  "text": "Which service do you need?",
  "list": {
    "button_text": "Choose a service",
    "sections": [
      {
        "title": "Appointments",
        "rows": [
          {
            "id": "book_appointment",
            "title": "Book an appointment",
            "description": "Choose a date for your visit"
          },
          {
            "id": "reschedule_appointment",
            "title": "Reschedule",
            "description": "Change an existing booking"
          }
        ]
      },
      {
        "title": "Support",
        "rows": [
          { "id": "contact_support", "title": "Contact support" }
        ]
      }
    ]
  }
}

Row IDs must be unique within the list and contain 1–128 UTF-8 bytes. Keep button_text to 20 characters, section and row titles to 24 characters, and optional row descriptions to 72 characters. A selection returns the row’s id and title in message.list_reply through inbound webhooks.

Preview interactive messages

The dashboard’s Templates builder previews buttons and lists and copies request JSON; it does not save or send templates.

Interactive rendering is experimental and depends on the recipient’s WhatsApp client. Provider acceptance does not guarantee that a button or list renders. Receive supported selections through inbound webhooks, and validate them before taking business actions.

Retry without sending twice

Choose an idempotency key once for each logical message, and persist it with the request in your application. A UUID is a suitable key. Retries must keep both the key and request unchanged.

RequestResult
A completed new submission201 Created, with a message ID.
Matching retry while processing202 Accepted.
Matching retry after processing200 OK, with the existing result.
Same key with different content409 IDEMPOTENCY_CONFLICT.

If the connection times out or the outcome is uncertain, inspect the existing message and retry with the same key. A new key can create a second message and consume another unit. For images, comparison uses the URL and request values, not downloaded image bytes.

Read delivery status

Retrieve a message by ID or open Messages in the dashboard. API detail responses include status history, oldest update first.

StatusMeaning
processingSubmission is in progress.
acceptedAccepted for sending, not confirmed delivered.
deliveredDelivery was confirmed.
readReading was confirmed.
failedSending failed. Inspect the failure code.
unknownThe outcome is unconfirmed; do not assume it is safe to resend.

Not every route reports every status. SMS does not currently ingest delivery receipts. Inbound webhooks do not report outbound message status; inspect the message record instead.

Handle common failures

  • 402 PLAN_EXPIRED: check WhatsApp trial or paid access in Billing.
  • 429 MESSAGE_QUOTA_EXCEEDED: check remaining WhatsApp messages or SMS segments. This is not a request to retry immediately.
  • CHANNEL_DISCONNECTED: reconnect the WhatsApp number before trying again.
  • 422 CHANNEL_TYPE_UNAVAILABLE: the selected messaging provider is not configured.
  • 409 IDEMPOTENCY_CONFLICT: compare the request with the original; do not change keys to bypass an uncertain send.

See Billing for how messages and retries count toward your allowance.