API Endpoints

Send WhatsApp Template Messages

This API allows external systems to send WhatsApp Template Messages through WappCloud’s platform.

Endpoint

POST https://client-api.wappcloud.com/api/v1/external/process

Headers

Setting Up the Request Body in Postman

• In Postman, select the Body tab.

• Choose raw.

• From the dropdown, select JSON.

• Paste your JSON payload in the text area.

Template Request Payloads

1. Static Template

{
  "contact_number": "+9199xxxxxx",
  "message_uid": "1234",          // optional
  "message": {
    "template_name": "hello_world"
  }
}

2. Dynamic Text Header and Body

{
  "contact_number": "+9199xxxxxx",
  "message_uid": "1234",          // optional
  "message": {
    "template_name": "sample_v9",
    "header": {
      "type": "text",
      "text": "sample"
    },
    "body": {
      "variables": {
        "1": "John Doe",
        "2": "Gojo"
      }
    }
  }
}

3. Dynamic Header Image

{
  "contact_number": "+9199xxxxxx",
  "message_uid": "1234",          // optional
  "message": {
    "template_name": "img1",
    "header": {
      "type": "image",
      "url": "https://example.com/image.png"
    }
  }
}

4. Dynamic Button

{
  "contact_number": "+9199xxxxxx",
  "message_uid": "1234",          // optional
  "message": {
    "template_name": "dynamic_button_v1",
    "buttons": [
      {
        "type": "url",
        "text": "1223454"
      }
    ]
  }
}

5. Dynamic Header Video

Same idea as a dynamic header image, but with "type": "video". See Video File Requirements below before sending — this is the most common reason a video “sends successfully” but never actually shows up on the recipient’s phone.

{
  "contact_number": "+9199xxxxxx",
  "message_uid": "1234",          // optional
  "message": {
    "template_name": "video_demo_v1",
    "header": {
      "type": "video",
      "url": "https://example.com/product-demo.mp4"
    }
  }
}

6. Carousel Template

If your template was created as a Carousel (multiple swipeable cards, each with its own image and buttons), send one entry per card in the carousel array, in the same order the cards were defined when the template was created.

{
  "contact_number": "+9199xxxxxx",
  "message_uid": "1234",          // optional
  "message": {
    "template_name": "product_carousel_v1",
    "carousel": [
      {
        "header": {
          "type": "image",
          "url": "https://example.com/product-1.jpg"
        },
        "body": {
          "variables": { "1": "Blue Sneakers", "2": "1,999" }
        },
        "buttons": [
          { "type": "url", "text": "https://shop.example.com/blue-sneakers" }
        ]
      },
      {
        "header": {
          "type": "image",
          "url": "https://example.com/product-2.jpg"
        },
        "body": {
          "variables": { "1": "Red Sneakers", "2": "2,199" }
        },
        "buttons": [
          { "type": "url", "text": "https://shop.example.com/red-sneakers" }
        ]
      }
    ]
  }
}

• Every card must supply whatever the template’s card design requires (a header image/video is almost always required; body/button variables only if that card has them).
• The number of cards you send does not have to match every card defined in the template, but each card you do send must be complete on its own.

Response (Success)

{
  "code": 200,
  "success": true,
  "data": {
    "message_uid": "DSFDS223432432"
  },
  "message": "Request processed and messages sent successfully."
}

Notes

• Do not change field names — they must match exactly (contact_number, message, template_name, etc.).

• Contact number must start with + and include country code. No dashes or spaces. Example: +9199xxxxxx.

• message_uid is optional.

• Template names must match exactly as configured in Meta WhatsApp Business Manager.

• For templates, variable order must follow (1, 2, 3, …).

• Media links must be HTTPS. Any time you pass a link to an image, video, audio file, or document (for example the url field in a header, or a card image in a carousel), it must be a public https:// link. WhatsApp fetches the file from that link when it delivers the message — a plain http:// link, a link behind a login, or a broken/expired link will cause the message to fail or arrive without the media.

• Sending a video? See Video File Requirements below — an .mp4 file extension alone does not guarantee it will play on WhatsApp.

Video File Requirements

If a video message sends without an error but the recipient can’t play it (or it plays fine in a browser but not on their phone), the video file itself is almost always the cause — not your request.

Think of MP4 like a shipping box. The .mp4 extension only tells you the shape of the box — it does not tell you what’s packed inside. Two .mp4 files can look identical from the outside but be encoded completely differently on the inside. WhatsApp only reliably plays videos packed a specific way:

• Video codec: H.264
• Audio codec: AAC
• Pixel format: yuv420p
• Container: MP4

A video exported from some editing tools, screen recorders, or phone cameras may be saved as .mp4 but actually packed with a different codec inside (commonly H.265/HEVC). That file will often play fine in a web browser or on a computer, but fail — or show a blank/black screen — when opened inside WhatsApp on a phone.

What to do if a video won’t send or won’t play:

1. Confirm the video URL is https:// and publicly accessible (not behind a login, VPN, or firewall).
2. Re-encode the video using any standard video converter (for example HandBrake, or an online MP4 converter), and make sure the output settings target H.264 video + AAC audio inside an MP4 container. Most converters offer this as a preset (often labeled “Web” or “WhatsApp compatible” or simply “H.264”).
3. Re-upload or re-link the newly converted file and try sending again.

This applies both to video sent as a template header (via a url) and to any video header uploaded through Upload Media when creating a template.

WhatsApp Direct Messaging API

This API allows external systems to send direct text and media messages through WappCloud’s platform.

Endpoint

POST https://client-api.wappcloud.com/api/v1/external/process

Headers

Text Message — Request Payload

{
  "contact_number": "+9199xxxxxx",
  "messageType": "text",
  "message": {
    "messageBody": "Hello, this is a test message"
  }
}

Text Message — Response (Success)

{
  "success": true,
  "code": 200,
  "message": "Message sent successfully"
}

Media Messages (Image, Video, Document, Audio)

To send media, use form-data in Postman:

• Go to the Body tab.

• Select form-data.

• Add the following fields:

Media Response (Success)

{
  "success": true,
  "code": 200,
  "message": "Message sent successfully"
}

Notes:

• Do not change field names — they must match exactly (contact_number, messageType, mediaType, chatMedia).

• Contact number must start with + and include country code. No dashes or spaces. Example: +9199xxxxxx.

• For media messages, use form-data instead of raw JSON.

• Supported media types: image, video, document, audio.

• Make sure to set the correct mediaType that matches your uploaded file type.

• Sending a video file this way? The same Video File Requirements apply — an .mp4 extension alone doesn’t guarantee WhatsApp will play it. Re-encode with H.264 video + AAC audio if a video fails to display on mobile.