HomeFeatures
Pricing
AboutContact
Sign InStart for free
Developer Portal

Documentation

API reference, guides, and integration snippets to launch WhatsApp Business messaging in under 5 minutes.

rocket_launch

Getting Started

MSGTODAY provides access to the official Meta WhatsApp Business Cloud API. Integrate high-speed messaging into your sign-up flows, tracking mechanisms, alerts, or customer support workflows.

Integration Workflow

  1. Create your account and complete verification on our console.
  2. Claim test credits and configure your Sandbox phone number to test incoming and outgoing message loops.
  3. Link your official Meta WhatsApp Business account to move into Production and acquire dedicated API keys.
vpn_key

Authentication

Every API call must present credentials via the Authorization header using standard Bearer Token authorization. Secure your API key like you would a password.

# Include Bearer token in your HTTP requests
Authorization: Bearer msg_live_79a2bbd73c...
send

Send Message API

Send messages programmatically using the unified message sending endpoint. This API dynamically handles text, replies, location coordinates, contact cards, media files, and interactive templates.

POST/api/v1/messages
Content-Type: application/json

Request Body Fields

FieldTypeDescription
tostringRecipient phone number in E.164 format (e.g. "+919876543210").
typestringMessage category: text, image, video, document, location, contact, interactive, catalogue, or template.
textstringMessage body string (required for type text).
replyToMessageIdstringID of the message you want to reply to (optional).
mediaUrlstringStatic asset URL link (required for media types).
templateobjectTemplate configuration containing name, language, and parameters array.

Select Payload Schema Template

{
  "to": "+919876543210",
  "type": "text",
  "text": "Hello Aarav! Welcome to MSGTODAY."
}
forum

Fetch Messages API

Fetch workspace message records. You can filter the history logs using specific recipient phone numbers.

GET/api/v1/messages
Accept: application/json

Query Parameters

FieldTypeDescription
contactPhoneNumberstringFilter messages matching specific phone number (Optional).
limitintegerLimit records returned. Range: 1-100 (Default: 50).

Response Example

[
  {
    "messageId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "direction": "incoming",
    "type": "text",
    "content": { "text": "Hello support" },
    "status": "delivered",
    "timestamp": "2026-07-03T18:00:00.000Z",
    "recipientPhoneNumber": "+919876543210"
  }
]
upload_file

Media Upload API

Acquire secure presigned upload gateway links to host your images, documents, and videos directly prior to sending media messages.

GET/api/v1/media/upload-url
Accept: application/json

Query Parameters

FieldTypeDescription
fileNamestringName of the file to be uploaded (e.g. "invoice.pdf") (Required).
fileTypestringThe MIME type of the file (Optional).

Response Example

{
  "uploadUrl": "https://api.msgtoday.com/api/v1/media/upload-direct?path=media/ab12cd34_filename.png",
  "fileUrl": "https://gpdcodlvccdziwucfjdo.supabase.co/storage/v1/object/public/media/media/ab12cd34_filename.png",
  "headers": {
    "Content-Type": "image/png"
  }
}
sync_alt

Webhooks Integration

Configure Webhooks to listen for status reports (sent, delivered, read status updates) and customer-initiated message events. Register your webhook URL inside the console settings page.

All Webhook payload structures contain an action event key along with timestamps:

// Webhook POST JSON structure snippet
{ "event": "message.status_update", "message_id": "msg_99b0c27384a2", "status": "read", "timestamp": "2026-06-29T20:25:01Z" }
error

Error Codes

Standard error responses return an HTTP status code alongside a JSON body error payload containing diagnostic info.

CodeTitleReason / Fix
400Bad RequestMissing fields or invalid formatting (e.g. invalid phone format).
401UnauthorizedInvalid API credentials or token expired. Verify your token in Console.
429Rate LimitedAPI limits exceeded. Retry with exponential backoff configuration.
502Provider ErrorMeta servers could not receive routing request. Auto fallback will trigger.
schema

WhatsApp Flows

WhatsApp Flows allow customers to complete multi-step actions (such as booking appointments, lead capture forms, or feedback surveys) directly inside the WhatsApp chat thread without opening external browsers.

Learn About WhatsApp Flows

A WhatsApp Flow is represented as a flowchart consisting of one or more interactive screens. The entry point of a Flow must have the ID screen-welcome. You can build these Flows inside the MsgToday Flow Editor and test their transitions in real-time.

Flow screen structure:

// FlowScreen JSON interface
{ "id": "screen-welcome", "title": "Appointment Details", "body": "Welcome! Please select a service below:", "components": [ { "id": "service-dropdown", "type": "dropdown", "label": "Select Service", "options": ["🦷 Dental Cleaning", "🏥 Consultation"] }, { "id": "next-btn", "type": "button", "label": "Continue", "targetScreenId": "screen-schedule" } ], "position": { "x": 80, "y": 150 } }

Integration & Production Publishing

To trigger an interactive Flow in production, send a message of type interactive referencing the template ID or use our API. When the user interacts with the Flow screens, the selections are dispatched as a webhook event of type interactive to your configured endpoints.

view_carousel

WhatsApp Carousel Templates

Media card carousel templates let you showcase multiple products or offers in a single scrollable marketing template message on WhatsApp. Each product appears as a horizontally scrollable card, allowing users to browse, compare, and act on offers without leaving the chat thread.

Components of a Carousel

Each carousel consists of a parent message body text and a horizontally scrollable carousel of up to 10 product media cards.

  • Header (Required): An image or video asset representing the product.
  • Body Text (Optional): Short descriptive text, such as a product name, price, or description.
  • Buttons (Optional, up to 2 per card): Mixable card actions including URL buttons, Call buttons, and Quick Reply buttons.
Consistency Requirement: All cards in a single carousel template must use the same set of components. For example, if Card #1 includes a body text and two buttons, all cards in the template must also include a body text and two buttons.

Template Registration JSON Payload

Below is the standard JSON layout required when registering a carousel template via our APIs:

// Carousel Template Payload
{ "name": "sample_carousel_template10", "language": "en", "category": "MARKETING", "components": [ { "type": "BODY", "text": "Hi *{{1}}*. Check out our recommendations:", "example": { "body_text": [["Pablo"]] } }, { "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "format": "IMAGE", "example": { "header_handle": ["4::aW1hZ2UvanBn..."] } }, { "type": "BODY", "text": "Video API: as low as {{1}} USD/min.", "example": { "body_text": [["0.00395"]] } }, { "type": "BUTTONS", "buttons": [ { "type": "URL", "text": "Docs", "url": "https://tokbox.com/developer/" }, { "type": "QUICK_REPLY", "text": "Tell me more!" } ] } ] } ] } ] }
Chat on WhatsApp