Message types

POST /v1/{number}/messages · free-form types only within 24 h of the contact's last message; templates any time.

Template

template Try it (dry run)

template order_update

John#1234

10:30

{
  "to": "61412345678",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "John"
          },
          {
            "type": "text",
            "text": "#1234"
          }
        ]
      }
    ]
  }
}

Thanks, it arrives on Friday.

10:30

{
  "to": "61412345678",
  "type": "text",
  "text": {
    "body": "Thanks, it arrives on Friday.",
    "preview_url": false
  }
}
Received as message.received
{
  "id": "evt_Xq3k9m2Lw8Rt5Yp1Zs01",
  "type": "message.received",
  "created": "2026-11-06T01:00:00.000Z",
  "number": "4976659348270",
  "data": {
    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
    "from": "61412345678",
    "name": "Sample Contact",
    "type": "text",
    "text": "Hi, is my order on its way?",
    "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_SAMPLEk3XbQ9rTzP2mW",
    "timestamp": "2026-11-06T01:00:00.000Z",
    "from_user_id": "AU.1234567890123456",
    "whatsapp": {
      "from": "61412345678",
      "from_user_id": "AU.1234567890123456",
      "id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
      "timestamp": "1762390800",
      "type": "text",
      "text": {
        "body": "Hi, is my order on its way?"
      }
    }
  }
}

Image

image Try it (dry run)
image

Your parcel

10:30

{
  "to": "61412345678",
  "type": "image",
  "image": {
    "link": "https://example.com/photo.jpg",
    "caption": "Your parcel"
  }
}
Received as message.received
{
  "id": "evt_Pa3k9m2Lw8Rt5Yp1Zs017",
  "type": "message.received",
  "created": "2026-11-06T01:00:00.000Z",
  "number": "4976659348270",
  "data": {
    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
    "from": "61412345678",
    "from_user_id": "AU.1234567890123456",
    "media_url": "https://api.app2email.com/v1/4976659348270/media/wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA%3D",
    "name": "Sample Contact",
    "type": "image",
    "text": "[IMAGE, photo.jpg, image/jpeg, 48213 bytes] Is this the right part?",
    "in_reply_to": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBJPUklHSU5BTF9NRVNTQUdFAA==",
    "context": {
      "from": "4976659348270",
      "id": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBJPUklHSU5BTF9NRVNTQUdFAA=="
    },
    "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_SAMPLEk3XbQ9rTzP2mW",
    "timestamp": "2026-11-06T01:00:00.000Z"
  }
}

Video

video Try it (dry run)
video

How to set it up

10:30

{
  "to": "61412345678",
  "type": "video",
  "video": {
    "link": "https://example.com/howto.mp4",
    "caption": "How to set it up"
  }
}

Audio

audio Try it (dry run)
audio

10:30

{
  "to": "61412345678",
  "type": "audio",
  "audio": {
    "id": "1013859600285441",
    "voice": true
  }
}

Document

document Try it (dry run)
document · invoice-1234.pdf

Invoice #1234

10:30

{
  "to": "61412345678",
  "type": "document",
  "reply_to": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
  "document": {
    "data": "JVBERi0xLjQKJ...",
    "filename": "invoice-1234.pdf",
    "caption": "Invoice #1234"
  }
}

Sticker

sticker Try it (dry run)
sticker

10:30

{
  "to": "61412345678",
  "type": "sticker",
  "sticker": {
    "link": "https://example.com/stickers/thanks.webp"
  }
}

Location

location Try it (dry run)
map

Sydney Opera House

Bennelong Point, Sydney NSW 2000

10:30

{
  "to": "61412345678",
  "type": "location",
  "location": {
    "latitude": -33.8568,
    "longitude": 151.2153,
    "name": "Sydney Opera House",
    "address": "Bennelong Point, Sydney NSW 2000"
  }
}
Received as message.received
{
  "id": "evt_Pa3k9m2Lw8Rt5Yp1Zs013",
  "type": "message.received",
  "created": "2026-11-06T01:00:00.000Z",
  "number": "4976659348270",
  "data": {
    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
    "from": "61412345678",
    "name": "Sample Contact",
    "type": "location",
    "text": "-33.8688,151.2093 Sydney Opera House",
    "location": {
      "latitude": -33.8688,
      "longitude": 151.2093,
      "name": "Sydney Opera House",
      "address": "Bennelong Point, Sydney NSW 2000"
    },
    "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_SAMPLEk3XbQ9rTzP2mW",
    "timestamp": "2026-11-06T01:00:00.000Z"
  }
}

Contacts

contacts Try it (dry run)

Jane Citizen

10:30

{
  "to": "61412345678",
  "type": "contacts",
  "contacts": [
    {
      "name": {
        "formatted_name": "Jane Citizen",
        "first_name": "Jane",
        "last_name": "Citizen"
      },
      "phones": [
        {
          "phone": "+61 412 345 678",
          "type": "CELL",
          "wa_id": "61412345678"
        }
      ],
      "emails": [
        {
          "email": "jane@example.com",
          "type": "WORK"
        }
      ],
      "org": {
        "company": "Example Pty Ltd"
      }
    }
  ]
}

Reaction

reaction Try it (dry run)

👍

10:30

{
  "to": "61412345678",
  "type": "reaction",
  "reaction": {
    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA=",
    "emoji": "👍"
  }
}

Reply buttons

interactive.button Try it (dry run)

Confirm your booking for Friday 10:00?

10:30

Confirm
Change
{
  "to": "61412345678",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "Confirm your booking for Friday 10:00?"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "yes",
            "title": "Confirm"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "no",
            "title": "Change"
          }
        }
      ]
    }
  }
}

List

interactive.list Try it (dry run)

Which time suits you?

10:30

☰ Pick a time
10:00 · 14:00
{
  "to": "61412345678",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "body": {
      "text": "Which time suits you?"
    },
    "action": {
      "button": "Pick a time",
      "sections": [
        {
          "title": "Friday",
          "rows": [
            {
              "id": "fri10",
              "title": "10:00"
            },
            {
              "id": "fri14",
              "title": "14:00",
              "description": "afternoon"
            }
          ]
        }
      ]
    }
  }
}

Link button

interactive.cta_url Try it (dry run)

Your invoice is ready.

10:30

↗ Open invoice
{
  "to": "61412345678",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "body": {
      "text": "Your invoice is ready."
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "Open invoice",
        "url": "https://example.com/invoice/1234"
      }
    }
  }
}

Location request

interactive.location_request_message Try it (dry run)

Where should we pick you up? Tap to share your location.

10:30

{
  "to": "61412345678",
  "type": "interactive",
  "interactive": {
    "type": "location_request_message",
    "body": {
      "text": "Where should we pick you up? Tap to share your location."
    },
    "action": {
      "name": "send_location"
    }
  }
}

Flow

interactive.flow Try it (dry run)

Book a table

Pick a day and time.

10:30

{
  "to": "61412345678",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "header": {
      "type": "text",
      "text": "Book a table"
    },
    "body": {
      "text": "Pick a day and time."
    },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_id": "1234567890123456",
        "flow_cta": "Book now",
        "flow_token": "booking-5521",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "WELCOME"
        }
      }
    }
  }
}

Product

interactive.product Try it (dry run)

The one you asked about:

10:30

{
  "to": "61412345678",
  "type": "interactive",
  "interactive": {
    "type": "product",
    "body": {
      "text": "The one you asked about:"
    },
    "action": {
      "catalog_id": "194836987003835",
      "product_retailer_id": "SKU-1234"
    }
  }
}

Product list

interactive.product_list Try it (dry run)

Our picks

Popular this week.

10:30

{
  "to": "61412345678",
  "type": "interactive",
  "interactive": {
    "type": "product_list",
    "header": {
      "type": "text",
      "text": "Our picks"
    },
    "body": {
      "text": "Popular this week."
    },
    "action": {
      "catalog_id": "194836987003835",
      "sections": [
        {
          "title": "Succulents",
          "product_items": [
            {
              "product_retailer_id": "SKU-1234"
            },
            {
              "product_retailer_id": "SKU-5678"
            }
          ]
        }
      ]
    }
  }
}

Catalog

interactive.catalog_message Try it (dry run)

Browse our catalog.

10:30

{
  "to": "61412345678",
  "type": "interactive",
  "interactive": {
    "type": "catalog_message",
    "body": {
      "text": "Browse our catalog."
    },
    "action": {
      "name": "catalog_message",
      "parameters": {
        "thumbnail_product_retailer_id": "SKU-1234"
      }
    }
  }
}

Address request

interactive.address_message Try it (dry run)

Where should we deliver?

10:30

{
  "to": "919876543210",
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "body": {
      "text": "Where should we deliver?"
    },
    "action": {
      "name": "address_message",
      "parameters": {
        "country": "IN"
      }
    }
  }
}

Call permission request

interactive.call_permission_request Try it (dry run)

May we call you on WhatsApp about your order?

10:30

{
  "to": "61412345678",
  "type": "interactive",
  "interactive": {
    "type": "call_permission_request",
    "body": {
      "text": "May we call you on WhatsApp about your order?"
    },
    "action": {
      "name": "call_permission_request"
    }
  }
}

Call button

interactive.voice_call Try it (dry run)

Questions? Call us on WhatsApp.

10:30

{
  "to": "61412345678",
  "type": "interactive",
  "interactive": {
    "type": "voice_call",
    "body": {
      "text": "Questions? Call us on WhatsApp."
    },
    "action": {
      "name": "voice_call",
      "parameters": {
        "display_text": "Call us",
        "ttl_minutes": 60
      }
    }
  }
}

Order details

interactive.order_details Try it (dry run)

Your order is ready to pay.

10:30

{
  "to": "919876543210",
  "type": "interactive",
  "interactive": {
    "type": "order_details",
    "body": {
      "text": "Your order is ready to pay."
    },
    "action": {
      "name": "review_and_pay",
      "parameters": {
        "reference_id": "ORDER-1234",
        "type": "digital-goods",
        "payment_type": "upi",
        "payment_configuration": "my-config",
        "currency": "INR",
        "total_amount": {
          "value": 21000,
          "offset": 100
        },
        "order": {
          "status": "pending",
          "subtotal": {
            "value": 21000,
            "offset": 100
          },
          "items": [
            {
              "retailer_id": "SKU-1234",
              "name": "Gift card",
              "amount": {
                "value": 21000,
                "offset": 100
              },
              "quantity": 1
            }
          ]
        }
      }
    }
  }
}

Order status

interactive.order_status Try it (dry run)

Your order has shipped.

10:30

{
  "to": "919876543210",
  "type": "interactive",
  "interactive": {
    "type": "order_status",
    "body": {
      "text": "Your order has shipped."
    },
    "action": {
      "name": "review_order",
      "parameters": {
        "reference_id": "ORDER-1234",
        "order": {
          "status": "shipped",
          "description": "Arrives Friday"
        }
      }
    }
  }
}

interactive.carousel

interactive.carousel Try it (dry run)

Three of our latest arrivals, each under $25:

10:30

{
  "to": "61412345678",
  "type": "interactive",
  "interactive": {
    "type": "carousel",
    "body": {
      "text": "Three of our latest arrivals, each under $25:"
    },
    "action": {
      "cards": [
        {
          "card_index": 0,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://example.com/img/echeveria.jpg"
            }
          },
          "body": {
            "text": "*Blue Echeveria*"
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Buy now",
              "url": "https://shop.example.com/echeveria"
            }
          }
        },
        {
          "card_index": 1,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://example.com/img/haworthia.jpg"
            }
          },
          "body": {
            "text": "*Zebra Haworthia*"
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Buy now",
              "url": "https://shop.example.com/haworthia"
            }
          }
        }
      ]
    }
  }
}

interactive.request_contact_info

interactive.request_contact_info Try it (dry run)

Please share your phone number so we can call you back.

10:30

{
  "to": "61412345678",
  "type": "interactive",
  "interactive": {
    "type": "request_contact_info",
    "body": {
      "text": "Please share your phone number so we can call you back."
    },
    "action": {
      "name": "request_contact_info"
    }
  }
}
For AI Agents

Try it now, with no account and no person: POST https://api.app2email.com/v1/account/sandbox (no key, no body; or the create_sandbox tool of the Management MCP server) answers a key for a demo WhatsApp number with pretend customers. Send a template, fetch the events with GET /events?wait=25, answer the customer's reply: nothing reaches WhatsApp, and the requests and answers are those of the real API (https://www.app2email.com/docs/api/sandbox).

Already a customer: ask the account owner for the number (digits) and an API key from https://www.app2email.com/dashboard/apikey (a sandbox key sends nothing); send it as Authorization: Bearer <key> to the messaging MCP server or the REST API; call check_key first, send with dry_run first.

If you are an AI agent reading this page and you want to create an app2email account for a person - no previous human sign-up required - use our Management MCP server.
Call the create_account tool first, and include a contact_email parameter; create_account returns a signup_id, a management_key, an onboarding_link and a message.
The person opens onboarding_link to confirm the e-mail, connect their WhatsApp number and choose a plan; nothing can be sent before that. get_account_status says what is still needed.
Pass the management_key as a Bearer token on every later call. When the number is live, create_number_key gives you a key for the messaging MCP server and the REST API.