This guide walks you through sending your first WhatsApp message using the InstaMessage Messaging API.

You’ll learn how to authenticate, use WhatsApp Templates, send free-form messages inside the 24-hour service window, and personalise messages with dynamic fields.

To use WhatsApp through InstaMessage, you will need the following:

If you're new to InstaMessage, contact our sales team to get started:

[email protected]

To send WhatsApp messages, you need at least one phone number:

1. Go to Admin → Purchase Numbers
2. Choose a number
3. Click Buy

This number becomes the WhatsApp number connected to your InstaMessage account (the number messages will be sent from).

If your WhatsApp Business Account (WABA) has an approved business profile or Meta verification, customers will see your business name instead of your phone number.

To send WhatsApp messages, your WhatsApp Business Account (WABA) must be connected to InstaMessage.

You can connect your account under:

Admin → WhatsApp

Once connected, you can send WhatsApp messages via the API, subject to WhatsApp messaging rules.

If your WhatsApp account is not connected, API requests to send WhatsApp messages will return an error.

Full onboarding walkthrough is a coming soon.

You’ll need an API key to authenticate requests.

1. Go to Admin → API
2. Select Show Key under API Live Key
3. Copy your API Key

Your API key is tied to your InstaMessage account and authorises access to all InstaMessage APIs.

Important: Treat your API key like a password. Never share it publicly or commit it to source control.

Each account has a single active API key. Subaccounts and environments will be supported in future.

InstaMessage uses API key authentication.

Each API request must include a valid API key issued to your account.

Authorization: Bearer YOUR_API_KEY

All WhatsApp messages are sent using the unified messaging endpoint:

POST https://api.instamessage.co.uk/v1/messages

WhatsApp requires all business-initiated messages to use a Meta-approved Template.

Templates:

• Must be approved by Meta
• Contain placeholders for parameters
• Are categorised as Marketing, Utility, or Authentication

Template categories:

• Marketing – promotions and sales messages
• Utility – transactional updates (e.g. order confirmations, shipping alerts)
• Authentication – one-time passcodes and password resets

You can create and manage WhatsApp Templates in InstaMessage from the Template screen.

Once you’ve provided the required fields, the behaviour of your message depends on the message_type.

WhatsApp supports three primary message types:

Note: Free-form messages (text or media) can only be sent inside the 24-hour customer service window.

Outside the 24-hour window → You must use a Template

You can only initiate a conversation using a Template.

Inside the 24-hour window → You may send free-form messages

A 24-hour customer service window opens every time a customer sends you a message, including replies, media, or any inbound message on WhatsApp.

Inside this window, you may send free-form messages, including:

• Text messages
• Media messages
• Personalised messages using injected_fields

Free-form WhatsApp messages can contain named placeholders (e.g. {first_name}) and you can supply values using injected_fields.

• injected_fields are values supplied at send time and are used only for this message.
• If a contact exists, InstaMessage can also use stored contact fields and custom attributes.
• If a field exists in both places, injected_fields takes precedence.

• Contact first_name = "Adam"
• You send injected_fields.first_name = "Eve"
• {{first_name}} renders as "Eve"

WhatsApp templates do not support named placeholders. They use positional placeholders instead (see below).

• WhatsApp templates use positional placeholders such as {{1}}, {{2}}.

Parameters must be passed in order via template.parameters. If a parameter is missing or out of order, WhatsApp will reject the message.

Templates use an ordered parameters array matching the placeholders in your approved Template.

curl -X POST "https://api.instamessage.co.uk/v1/messages" \
  -H "Authorization: Bearer $IM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+447123456789",
    "message_type": "template",
    "template": {
      "id": "PfjZ****************",
      "parameters": ["Alex", "12345"]
    }
  }'

This only works if the customer has already messaged you (the 24-hour service window is open).

{
  "channel": "whatsapp",
  "to": "+447123456789",
  "message_type": "text",
  "text": "Your table is confirmed for 7pm tonight."
}

Supported media types: image, video, audio, file & location

Example — WhatsApp image message

{
  "channel": "whatsapp",
  "to": "+447123456789",
  "message_type": "image",
  "image": { "url": "https://example.com/menu.jpg" }
}

Example — WhatsApp location message

{
  "channel": "whatsapp",
  "to": "+447123456789",
  "message_type": "location",
  "location": {
    "latitude": 51.5074,
    "longitude": -0.1278,
    "name": "London",
    "address": "10 Downing Street"
  }
}

WhatsApp location messages support static locations only (no live location).

Inside the 24-hour window you can personalise messages using injected_fields.

Example — Personalised WhatsApp message:

{
  "channel": "whatsapp",
  "to": "+447123456789",
  "message_type": "text",
  "text": "Hi {first_name}, your driver {driver} is 5 minutes away.",
  "injected_fields": {
    "first_name": "Sarah",
    "driver": "Tom"
  }
}

Rendered output:

Hi Sarah, your driver Tom is 5 minutes away.

Opt-out URLs are appended to free-form WhatsApp messages only when explicitly enabled.

Templates must include opt-out content directly if required.

InstaMessage reports delivery outcomes and inbound replies using account-level webhooks.

Webhooks are configured at the account level and apply to all WhatsApp messages sent via the API.

Configure your webhook URL in the InstaMessage dashboard under Admin → API

WhatsApp delivery status events may be sent multiple times for the same message (for example, delivered then later read).

WhatsApp messages can progress through multiple delivery states.

InstaMessage emits a webhook each time the status changes.

A status is considered final if no further states occur.

For example:

• If a message is delivered but never read, delivered is the final state.
• If a message is delivered and later read, read becomes the final state.

Example payload (delivered):

{
  "event_type": "message.status",
  "message_id": "abc123XYZ789def",
  "conversation_id": "conv456ABC123",
  "channel": "whatsapp",
  "to": "+447123456789",
  "status": "delivered",
  "timestamp": "2026-01-14T12:03:11Z"
}

Example payload (read):

{
  "event_type": "message.status",
  "message_id": "abc123XYZ789def",
  "conversation_id": "conv456ABC123",
  "channel": "whatsapp",
  "to": "+447123456789",
  "status": "read",
  "timestamp": "2026-01-14T12:10:04Z"
}

If a message is delivered but never read, you will receive delivered and no further updates.

When a customer replies to your WhatsApp message, InstaMessage sends an inbound webhook event.

Inbound reply webhooks are sent once per inbound message.

Example payload:

{
  "event_type": "message.inbound",
  "message_id": "msg_in_789XYZ",
  "conversation_id": "conv456ABC123",
  "channel": "whatsapp",
  "from": "+447123456789",
  "text": "Yes please",
  "timestamp": "2026-01-14T12:05:42Z"
}

If you miss a webhook delivery, you can retrieve the latest delivery status using the message ID returned when the message was created.

See: Delivery tracking → Delivery Receipts & Message Status

{
  "message_id": "abc123XYZ789def",
  "conversation_id": "conv456ABC123"
}

Delivery status and timestamps are provided asynchronously via webhooks or can be retrieved using the message ID.

After sending your first WhatsApp message, you may want to explore:

• Managing Templates → WhatsApp Templates
• Delivery tracking → Delivery Receipts & Message Status
• Customer replies → Inbound Messages & Replies
• Webhooks → Webhook Quick-Start

WhatsApp is a powerful conversational channel and InstaMessage simplifies the setup so your business can focus on delivering great customer experiences.