Back to home

Public reference

No login required to read this page. Integrations use workspace API keys from the dashboard (Sign in → Settings → API keys).

Public partner API (API keys)

Server-to-server integration for sending WhatsApp messages from your own backend without a user login. Authentication uses a workspace API key and secret (apiKey / apiSecret headers).

1. Creating API keys

  1. Sign in to the Flowziac dashboard.
  2. Open Settings (workspace settings).
  3. Find the API keys section (visible to workspace owners and admins only).
  4. Optionally enter a label, then click Generate key.
  5. Copy apiKey and apiSecret immediately. The secret is shown only once; store it in a secure environment variable on your server.

Revoked keys stop working at once. You can create multiple keys per workspace (e.g. staging vs production).

2. Base URL

Use this deployment’s partner API base (updates automatically on this page):

API base URLhttps://app.instawave.store/api/v1/public

3. Authentication

Send these headers on every request:

HeaderAlternativeValue
apiKeyX-API-KeyPublic key id (starts with pk_…)
apiSecretX-API-SecretSecret shown once at creation

Example:

apiKey: pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
apiSecret: <your-secret>
Content-Type: application/json

Invalid or revoked credentials return 401 with a JSON error body.

4. Endpoints

4.1 Send a message

POST /api/v1/public/messages/send

Recipient — provide either:

  • phone: WhatsApp-ready number (digits, country code, no + required in JSON), or
  • contactId: an existing contact id in that workspace.

Common optional fields

FieldDescription
phoneNumberIdInternal Flowziac phone number id if the workspace has more than one connected number; otherwise the active number is used.

Text message

{
  "type": "text",
  "phone": "919876543210",
  "content": "Hello from our system."
}

Template message (simple — recommended)

Use the approved template name as in the dashboard. Map {{1}}, {{2}}, … to string keys "1", "2", … in templateVariables.

{
  "type": "template",
  "phone": "919876543210",
  "templateName": "order_confirmation",
  "templateLanguage": "en",
  "templateVariables": {
    "1": "Jane",
    "2": "ORD-9921",
    "3": "Tomorrow 5pm"
  }
}
  • templateLanguage is optional; it helps match the stored template if you use locale codes (e.g. en vs en_US).
  • The template must be approved in Meta / Flowziac; pending or rejected templates cannot be sent.

Template message (advanced)

If you already build WhatsApp Cloud API components yourself, pass templateComponents (array) instead of templateVariables. Do not send both as the primary payload; the simple form uses variables only.

Media card carousel templates (marketing)

These templates are created in the Flowziac dashboard (Carousel (marketing) in the template builder). They are not the same as standard single-bubble templates.

  • Simple templateVariables mapping: Main bubble {{1}}, {{2}} map to keys "1", "2" as usual. For each carousel card, placeholders use keys c{cardIndex}_{slot} — e.g. card 0’s {{1}} is c0_1, card 1’s {{1}} is c1_1 (same pattern for URL variables on card buttons).
  • Structured carousel payload (optional): Instead of only flat templateVariables, you can send carousel.cards[] with bodyValues, buttonValues, and optional header.id (WhatsApp media id from upload — not a placeholder string). Body values can use numeric keys ("1", "2", …) matching {{1}}, {{2}}, or named keys; named keys are mapped to body slots in JSON key order (insertion order), so list fields in the same order as {{1}}, {{2}}, … in the template. Optional bodyParameters overrides main-bubble numeric slots ("1", "2") after templateVariables.
{
  "type": "template",
  "phone": "919876543210",
  "templateName": "your_carousel_template",
  "templateLanguage": "en_US",
  "templateVariables": { "1": "Main intro line" },
  "carousel": {
    "cards": [
      {
        "index": 0,
        "bodyValues": { "1": "Villa A", "2": "Dubai", "3": "1.2M" },
        "buttonValues": [
          {
            "index": 0,
            "sub_type": "url",
            "parameters": { "type": "text", "text": "slug-for-url" }
          }
        ],
        "header": { "format": "image", "id": "<whatsapp-media-id>" }
      }
    ]
  }
}
  • If you already build the Cloud API payload, pass templateComponents with body and carousel components per Meta’s send format.

Interactive message

{
  "type": "interactive",
  "phone": "919876543210",
  "content": "{\"type\":\"button\",\"body\":\"Choose\",\"buttons\":[...]}"
}

content must be a JSON string matching your app’s interactive payload format.

Success response (HTTP 201):

{
  "success": true,
  "data": {
    "id": "<message-id>",
    "status": "ACCEPTED",
    "message": "Message received and being sent to the recipient."
  }
}

4.2 List approved templates

GET /api/v1/public/templates

Returns approved templates for the workspace (same workspace as the API key). Use this to discover templateName and language codes.

Success (HTTP 200):

{
  "success": true,
  "data": {
    "templates": [ /* array of template records */ ]
  }
}

5. cURL examples

Replace placeholders and your base URL.

Send a template with variables

curl -sS -X POST "https://app.instawave.store/api/v1/public/messages/send" \
  -H "Content-Type: application/json" \
  -H "apiKey: pk_YOUR_KEY_ID" \
  -H "apiSecret: YOUR_SECRET" \
  -d '{
    "type": "template",
    "phone": "919876543210",
    "templateName": "payment_thank_you",
    "templateLanguage": "en_US",
    "templateVariables": {
      "1": "Shree Balaji Traders",
      "2": "₹75,600.00",
      "3": "INV-00516",
      "4": "Hiren Enterprises"
    }
  }'

Send plain text

curl -sS -X POST "https://app.instawave.store/api/v1/public/messages/send" \
  -H "Content-Type: application/json" \
  -H "apiKey: pk_YOUR_KEY_ID" \
  -H "apiSecret: YOUR_SECRET" \
  -d '{
    "type": "text",
    "phone": "919876543210",
    "content": "Your order has shipped."
  }'

List templates

curl -sS "https://app.instawave.store/api/v1/public/templates" \
  -H "apiKey: pk_YOUR_KEY_ID" \
  -H "apiSecret: YOUR_SECRET"

6. Security practices

  • Treat apiSecret like a password: environment variables or a secrets manager, never client-side code or public repos.
  • Prefer HTTPS only in production.
  • Rotate keys periodically; revoke old keys in Settings when no longer needed.
  • The public API is subject to the same global rate limits as the rest of the API unless you configure otherwise on your reverse proxy.

7. Related

  • Internal authenticated routes (JWT + workspace) use /api/v1/workspaces/:workspaceId/...; the partner API above does not require a Bearer token.
  • WhatsApp template content and variable rules follow Meta’s policies (e.g. body length vs number of variables).