Messaggio Multichannel Messaging Platform

https://messaggio.com/api-docs/
Admin
The Messaggio Multichannel Messaging Platform provides an API for distributing messages to clients...
Tokens:7,503
Snippets:56
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### API Response Example

Source: https://messaggio.com/api-docs

The standard JSON response format indicating the acceptance status of the request and individual message processing results.

```json
{
  "accepted_at": "2021-04-02T15-14-26Z",
  "messages": [
    {
      "recipient": {
        "phone": "35699554433"
},
      "message_id": "ff1ca1f9-94f2-4e43-97ed-a4ca672957c1"
},
    {
      "recipient": {
        "phone": "123-bad-phone"
},
      "error": {
        "title": "Bad data",
        "detail": "phone is incorrect"
}
}
]

}
```

--------------------------------

### WhatsApp Session Message Structures

Source: https://messaggio.com/api-docs

Examples of JSON structures for different WhatsApp session message types, including text, media, location, and contact objects.

```json
[{ "type": "text", "text": "Your text..." }]
```

```json
[{ "type": "media", "media": { "type": "image", "url": "https://example.com/product.jpg", "caption": "Our new product" } }]
```

```json
[{ "type": "media", "media": { "type": "video", "url": "https://example.com/tutorial.mp4", "caption": "Watch this video tutorial" } }]
```

```json
[{ "type": "media", "media": { "type": "audio", "url": "https://example.com/voice_message.ogg" } }]
```

```json
[{ "type": "media", "media": { "type": "document", "url": "https://example.com/price_list.pdf", "filename": "PriceList.pdf", "caption": "Current price list" } }]
```

```json
[{ "type": "media", "media": { "type": "sticker", "url": "https://example.com/sticker.webp" } }]
```

```json
[{ "type": "location", "location": { "latitude": 55.751244, "longitude": 37.618423, "name": "Location Name", "address": "Address" } }]
```

```json
[{ "type":"contact", "contact": { "name": { "prefix": "Dr.", "first_name": "John", "last_name": "Doe", "suffix": "Sr.", "formatted_name": "John Doe" }, "organisation": { "company": "LLC Example" }, "phones": [ { "type": "WORK", "phone": "+15551234567" } ], "messengers": [ { "service": "whatsapp", "username": "15551234567" } ] } }]
```

--------------------------------

### Response structure for message status

Source: https://messaggio.com/api-docs

Example of a successful 200 OK response containing message statuses or error details.

```json
{
  "statuses": [
    {
      "message_id": "073ff427-5fd3-4cde-b611-6071d75ec7eb",
      "type": "status",
      "status": {
        "message_id": "073ff427-5fd3-4cde-b611-6071d75ec7eb",
        "channel": "sms",
        "status": 70,
        "timestamp": "2022-01-26T14:15:22.484005102Z",
        "recipient": {
          "phone": "35699554433"
}
}
},
    {
      "message_id": "ef1ee51d-9dc9-40e5-8914-480d14210d6c",
      "type": "error",
      "error": "not found"
}
]

}
```

--------------------------------

### WhatsApp Template with Full Parameters

Source: https://messaggio.com/api-docs

Defines a template with variables in the header, body, and URL button.

```json
{"language":"en", "id": "full_param_template", "header": {...}, "body": {"parameters": [...]}, "buttons": [...]}
```

--------------------------------

### WhatsApp Template with Header and Body Variables

Source: https://messaggio.com/api-docs

Defines a template containing both header and body parameters.

```json
{"language":"en", "id": "header_body_param_template", "header": {...}, "body": {"parameters": [...]}}
```

--------------------------------

### WhatsApp Template with Dynamic URL Button

Source: https://messaggio.com/api-docs

Defines a template with a URL button using a dynamic parameter.

```json
{"type":"template", "template": {"language":"en", "id": "dynamic_url_template", "buttons":[{"type":"url", "url_parameter":"/link_param" }]}}
```

--------------------------------

### WhatsApp Template with Video Header

Source: https://messaggio.com/api-docs

Defines a template with a video in the header using a URL.

```json
{"language":"en", "id": "video_header_template", "header": {"type": "video", "video": {"url": "https://example.com/header.mp4"}}}
```

--------------------------------

### WhatsApp Template with Document Header

Source: https://messaggio.com/api-docs

Defines a template with a document in the header, including a filename.

```json
{"language":"en", "id": "document_header_template", "header": {"type": "document", "document": {"url": "https://example.com/document.pdf", "filename": "Offer.pdf"}}}
```

--------------------------------

### WhatsApp Template with Image Header

Source: https://messaggio.com/api-docs

Defines a template with an image in the header using a URL.

```json
{"language":"en", "id": "image_header_template", "header": {"type": "image", "image": {"url": "https://example.com/header.jpg"}}}
```

--------------------------------

### WhatsApp Template with Text Header

Source: https://messaggio.com/api-docs

Defines a template with a text variable in the header.

```json
{"language":"en", "id": "text_header_template", "header": {"type": "text", "text": "Variable text"}}
```

--------------------------------

### WhatsApp OTP Template

Source: https://messaggio.com/api-docs

Defines an OTP template with a copy code button.

```json
{"template": {"language":"en", "id": "otp_button_copy", "body": {"parameters":[{"text":"1234" }]}, "buttons":[{"type":"url", "url_parameter":"1234" }]}}
```

--------------------------------

### WhatsApp Template with Multiple Body Variables

Source: https://messaggio.com/api-docs

Defines a template with multiple variables in the message body provided in order.

```json
{"language":"en", "id": "multi_body_param_template", "body": {"parameters": [{"text": "Variable text 1"}, {"text": "Variable text 2"}]}}
```

--------------------------------

### WhatsApp Template with Location Header

Source: https://messaggio.com/api-docs

Defines a template with a location object in the header.

```json
{"language":"en", "id": "location_header_template", "header": {"type": "location", "location": {"type": "location", "longitude": 36.000155, "latitude": -5.610342, "name": "Point Name", "address": "Map address"}}}
```

--------------------------------

### WhatsApp Template with Body Variable

Source: https://messaggio.com/api-docs

Defines a template with a single variable in the message body.

```json
{"language":"en", "id": "body_param_template", "body": {"parameters": [{"text": "Variable text"}]}}
```

--------------------------------

### POST /send

Source: https://messaggio.com/api-docs

Sends a multichannel message to specified recipients using a prioritized list of channels.

```APIDOC
## POST /send

### Description
Sends a multichannel message to a list of recipients. The system attempts delivery based on the priority defined in the channels array.

### Method
POST

### Endpoint
/send

### Request Body
- **recipients** (array) - Required - An array of objects containing recipient phone numbers.
- **channels** (array) - Required - An array of strings listing channels in order of priority.
- **[channel_name]** (object) - Required - Configuration and content object for each channel specified (e.g., viber, whatsapp, sms).
- **options** (object) - Optional - Additional parameters including ttl, dlr_callback_url, and external_id.
```

--------------------------------

### WhatsApp Message Rules

Source: https://messaggio.com/api-docs

Outlines the rules for sending WhatsApp messages based on session status and template requirements.

```APIDOC
## WhatsApp Message Rules

### Description
- **Active Session**: If the user contacted you first or replied within the last 24 hours, you can send freeform messages.
- **Business-Initiated**: If outside the 24-hour window, you must use `type: template` with pre-registered and approved templates.
```

--------------------------------

### Inbound message from user Webhook

Source: https://messaggio.com/api-docs

Receives an inbound message from a user via a configured webhook.

```APIDOC
## POST /webhook/inbound

### Description
Receives an inbound message from a user. The callback is accepted and further attempts to post it will not be taken.

### Request Body
- **message_id** (string) - The message identifier in the system.
- **channel** (string) - Sending channel.
- **timestamp** (string) - Report sending time.
- **recipient_response** (object) - Details of the recipient response.

### Request Example
{
  "message_id": "703be60f-8e98-4d40-aa17-138703df6261",
  "channel": "viber",
  "timestamp": "2021-11-03T09-49-34Z",
  "type": "recipient_response",
  "recipient_response": {
    "recipient": {
      "phone": 35699554433
    },
    "from": "msgiotest",
    "content": {
      "type": "text",
      "text": "Inbound message text"
    }
  }
}

### Response
#### Success Response (200)
- Callback was accepted and further attempts to post it will not be taken.
```

--------------------------------

### POST https://msg.messaggio.com/api/v1/send

Source: https://messaggio.com/api-docs

Sends a message to one or more recipients using a specified priority order of communication channels.

```APIDOC
## POST https://msg.messaggio.com/api/v1/send

### Description
Sends a message to specified recipients. The system attempts delivery through the provided channels in the order defined. If delivery fails or TTL expires, the next channel in the list is used.

### Method
POST

### Endpoint
https://msg.messaggio.com/api/v1/send

### Parameters
#### Request Body
- **recipients** (Array of objects) - Required - List of message recipients. Each object must contain a 'phone' field (receiver's phone number without +).
- **channels** (Array of strings) - Required - Priority order of channels (viber, sms, flashcall, whatsapp, vk, mobileid, bottelegram, telegram-otp).
- **options** (object) - Optional - Additional parameters like ttl, dlr_callback_url, and external_id.
- **viber** (object) - Optional - Viber message configuration.
- **sms** (object) - Optional - SMS message configuration.
- **flashcall** (object) - Optional - Flashcall message configuration.
- **whatsapp** (object) - Optional - WhatsApp message configuration.
- **vk** (object) - Optional - VK message configuration.
- **mobileid** (object) - Optional - MobileID request configuration.
- **telegram** (object) - Optional - Telegram message configuration.
- **telegram-otp** (object) - Optional - Telegram-OTP message configuration.

### Request Example
{
  "recipients": [{"phone": "35699554433"}],
  "channels": ["whatsapp", "sms"],
  "options": {"ttl": 60},
  "sms": {"from": "CODE", "content": [{"type": "text", "text": "Hello"}]}
}

### Response
#### Success Response (200)
- **accepted_at** (string) - Timestamp of request acceptance.
- **messages** (Array) - List of message statuses per recipient.

#### Response Example
{
  "accepted_at": "2021-04-02T15-14-26Z",
  "messages": [
    {
      "recipient": {"phone": "35699554433"},
      "message_id": "ff1ca1f9-94f2-4e43-97ed-a4ca672957c1"
    }
  ]
}
```

--------------------------------

### ApiKeyAuth

Source: https://messaggio.com/api-docs

The API uses a security scheme based on an API Key provided in the request header.

```APIDOC
## Authentication

### Description
The API uses API Key authentication. The required credentials are provided via a custom header.

### Security Scheme
- **Type**: API Key
- **Header Name**: Messaggio-Login
- **Description**: The value for this header is located in the 'Project Login' field within the sender name information.
```

--------------------------------

### Flashcall Message Layout

Source: https://messaggio.com/api-docs

Defines the content structure for Flashcall messages, requiring a 4-digit numeric code.

```APIDOC
## Flashcall Message Layout

### Description
Flashcall messages require a 4-digit numeric code provided as text.

### Content Structure
- **Code**: `[{"type": "text", "text": "1234" }]`
```

--------------------------------

### SMS Message Layout

Source: https://messaggio.com/api-docs

The SMS channel supports only plain text content.

```json
[{"type": "text", "text": "Your text..." }]
```

--------------------------------

### SMS Message Layout

Source: https://messaggio.com/api-docs

Defines the content structure for SMS messages, which supports plain text only.

```APIDOC
## SMS Message Layout

### Description
SMS messages support only plain text content.

### Content Structure
- **Text**: `[{"type": "text", "text": "Your text..." }]`
```

--------------------------------

### Multichannel Message Request Payload

Source: https://messaggio.com/api-docs

A comprehensive JSON payload demonstrating the structure for sending messages across multiple channels including Viber, SMS, Flashcall, WhatsApp, VK, MobileID, and Telegram.

```json
{
  "recipients": [
    {
      "phone": "35699554433"
},
    {
      "phone": "123-bad-phone"
}
],
  "channels": [
    "whatsapp",
    "vk",
    "sms",
    "flashcall",
    "mobileid",
    "bottelegram"
],
  "options": {
    "ttl": 60,
    "dlr_callback_url": "https://example.com/dlr",
    "external_id": "messaggio-acc-external-id-0"
},
  "viber": {
    "from": "Viberfake",
    "label": "promotion",
    "content": [
      {
        "type": "image",
        "image": {
          "url": "https://example.com/cat.jpg"
}
},
      {
        "type": "text",
        "text": "Text of your Viber message"
},
      {
        "type": "button",
        "button": {
          "caption": "Press the button",
          "callback": "https://example.com"
}
},
      {
        "type": "otp",
        "otp": {
          "language": "en",
          "type": "basic",
          "basic": {
            "pin": "343536AB"
}
}
}
]
},
  "sms": {
    "from": "< CODE API VALUE >",
    "content": [
      {
        "type": "text",
        "text": "Text of your SMS message"
}
]
},
  "flashcall": {
    "from": "< CODE API VALUE >",
    "content": [
      {
        "type": "text",
        "text": "1234"
}
]
},
  "whatsapp": {
    "from": "< CODE API VALUE >",
    "content": [
      {
        "type": "location",
        "location": {
          "longitude": 27.380583,
          "latitude": 33.631839,
          "name": "Location name",
          "address": "Location address"
}
}
]
},
  "vk": {
    "from": "< CODE API VALUE >",
    "content": [
      {
        "type": "text",
        "text": "Text of your VK message"
}
]
},
  "mobileid": {
    "from": "< CODE API VALUE >",
    "content": [
      {
        "type": "auth",
        "auth": "push"
}
]
},
  "telegram": {
    "from": "5967047816:A232IjzIBjrjVv3XfnGF1mkpt3fvvzeTgVQ",
    "content": [
      {
        "type": "video",
        "video": {
          "file_url": "https://example.com/cat.mp4",
          "caption": "Video's caption"
}
},
      {
        "type": "button",
        "button": {
          "caption": "Press me",
          "callback": "https://example.com"
}
}
]
},
  "telegram-otp": {
    "from": "5967047816:A232IjzIBjrjVv3XfnGF1mkpt3fvvzeTgVQ",
    "content": {
      "code": "343637AB"
}
}

}
```

--------------------------------

### POST /api/v1/statuses

Source: https://messaggio.com/api-docs

Retrieves the current status of messages based on the provided message IDs and channel type.

```APIDOC
## POST /api/v1/statuses

### Description
Retrieves the delivery status for a list of message IDs across a specified communication channel.

### Method
POST

### Endpoint
https://msg.messaggio.com/api/v1/statuses

### Request Body
- **recipients** (Array of objects) - Required - List of message ID objects.
- **channels** (string) - Required - The channel used (e.g., "sms", "viber", "whatsapp").
- **sms** (Array of objects) - Optional - Configuration for SMS channel.
- **flashcall** (Array of objects) - Optional - Configuration for Flashcall channel.
- **viber** (Array of objects) - Optional - Configuration for Viber channel.
- **whatsapp** (Array of objects) - Optional - Configuration for WhatsApp channel.
- **vk** (Array of objects) - Optional - Configuration for VK channel.
- **mobileid** (Array of objects) - Optional - Configuration for MobileID channel.
- **bottelegram** (Array of objects) - Optional - Configuration for Telegram channel.
- **telegram-otp** (Array of objects) - Optional - Configuration for Telegram-OTP channel.

### Request Example
{
  "recipients": [
    { "id": "073ff427-5fd3-4cde-b611-6071d75ec7eb" },
    { "id": "ef1ee51d-9dc9-40e5-8914-480d14210d6c" }
  ],
  "channels": ["sms"],
  "sms": { "from": "EmptyTest" }
}

### Response
#### Success Response (200)
- **statuses** (Array of objects) - List of status objects for each requested message ID.

#### Response Example
{
  "statuses": [
    {
      "message_id": "073ff427-5fd3-4cde-b611-6071d75ec7eb",
      "type": "status",
      "status": {
        "message_id": "073ff427-5fd3-4cde-b611-6071d75ec7eb",
        "channel": "sms",
        "status": 70,
        "timestamp": "2022-01-26T14:15:22.484005102Z",
        "recipient": { "phone": "35699554433" }
      }
    },
    {
      "message_id": "ef1ee51d-9dc9-40e5-8914-480d14210d6c",
      "type": "error",
      "error": "not found"
    }
  ]
}
```

--------------------------------

### Define Telegram-otp message structure

Source: https://messaggio.com/api-docs

Structure for sending an OTP code via the Telegram-otp channel.

```json
{ "code": "1234" }
```

--------------------------------

### Define Telegram message content structures

Source: https://messaggio.com/api-docs

JSON structures for various Telegram message types including text, media, location, and contact, optionally with buttons.

```json
[{"type": "text", "text": { "text": "Your text..." } }]
```

```json
[{"type": "text", "text": { "text": "Your text..." }}, {"type": "button", "button": {"caption": "Button text", "callback": "https://..."}}]
```

```json
[{"type": "image", "image": {"file_url": "https://...", "caption": "Caption"}}]
```

```json
[{"type": "image", "image": {...}}, {"type": "button", "button": {...}}]
```

```json
[{"type": "document", "document": {"file_url": "https://...", "caption": "Caption"}}]
```

```json
[{"type": "document", "document": {...}}, {"type": "button", "button": {...}}]
```

```json
[{"type": "video", "video": {"file_url": "https://...", "caption": "Caption"}}]
```

```json
[{"type": "video", "video": {...}}, {"type": "button", "button": {...}}]
```

```json
[{"type": "location", "location": {"latitude": "40.689247", "longitude": "-74.044502"}}]
```

```json
[{"type": "location", "location": {...}}, {"type": "button", "button": {...}}]
```

```json
[{"type": "contact", "contact": {"phone_number": "+15551234567", "first_name": "John"}}]
```

```json
[{"type": "contact", "contact": {...}}, {"type": "button", "button": {...}}]
```

--------------------------------

### Viber Message Layouts

Source: https://messaggio.com/api-docs

JSON structures for various Viber message types including text, media, interactive elements, and surveys.

```json
[{"type": "text", "text": "Your text..." }]
```

```json
[{"type": "image", "image": { "url": "https://..." } }]
```

```json
[{"type": "text", "text": "Text..." }, { "type": "image", "image": { ... } }]
```

```json
[{"type": "text", "text": "Text..." }, { "type": "button", "button": { ... } }]
```

```json
[{"type": "text", "text": "Text..." }, { "type": "image", "image": { ... } }, { "type": "button", "button": { ... } }]
```

```json
[{"type": "video", "video": { "url": "https://...", "thumbnail": "https://...", "file_size_mb": 10, "duration_seconds": 60 } }]
```

```json
[{"type": "video", "video": { ... } }, { "type": "text", "text": "Text..." }]
```

```json
[{"type": "video", "video": { "button_caption": "Title", "caption": "https://..." } }, { "type": "text", "text": "Text..." }]
```

```json
[{"type": "file", "file": { ... } }]
```

```json
[{"type": "otp", "otp": { "type": "basic", "basic": { "pin": "12345" } } }]
```

```json
[{"type": "text", "text": "Text..." }, { "type": "carousel", "carousel": { "items": [...] } } ]
```

```json
[{"type": "text", "text": "Text..." }, { "type": "survey", "survey": { "options": [...] }} ]
```

--------------------------------

### Telegram Message Content Structures

Source: https://messaggio.com/api-docs

Defines the required JSON structures for different Telegram message types including text, media, location, and contact information, optionally with buttons.

```APIDOC
## Telegram Message Content

### Description
Defines the content array structure for Telegram messages. Each message consists of one or more objects defining the type and associated data.

### Request Body
- **content** (array) - Required - An array of objects defining the message layout.

### Example Structures
- **Text**: `[{"type": "text", "text": { "text": "Your text..." } }]`
- **Image**: `[{"type": "image", "image": {"file_url": "https://...", "caption": "Caption"}}]`
- **Location**: `[{"type": "location", "location": {"latitude": "40.689247", "longitude": "-74.044502"}}]`
- **Contact**: `[{"type": "contact", "contact": {"phone_number": "+15551234567", "first_name": "John"}}]`
```

--------------------------------

### Telegram-otp Message Content

Source: https://messaggio.com/api-docs

Defines the required structure for sending OTP codes via the Telegram-otp channel.

```APIDOC
## Telegram-otp Message Content

### Description
Defines the structure for sending an OTP code via the Telegram-otp channel. The code must be 4-8 characters in length.

### Request Body
- **code** (string) - Required - The OTP code to be sent.

### Example
{ "code": "1234" }
```

--------------------------------

### Viber Message Layouts

Source: https://messaggio.com/api-docs

Defines the content structures for various Viber message types including text, image, button, video, file, OTP, carousel, and survey.

```APIDOC
## Viber Message Layouts

### Description
Construct the `viber.content` field using an array of objects based on the desired layout. Supported types include text, image, button, video, file, otp, carousel, and survey.

### Content Structure Examples
- **Text**: `[{"type": "text", "text": "Your text..." }]`
- **Image**: `[{"type": "image", "image": { "url": "https://..." } }]`
- **OTP**: `[{"type": "otp", "otp": { "type": "basic", "basic": { "pin": "12345" } } }]`
- **Survey**: `[{"type": "text", "text": "Text..." }, { "type": "survey", "survey": { "options": [...] }} ]`
```

--------------------------------

### Flashcall Message Layout

Source: https://messaggio.com/api-docs

Flashcall messages require a 4-digit numeric code provided as text.

```json
[{"type": "text", "text": "1234" }]
```

--------------------------------

### Message status update Webhook

Source: https://messaggio.com/api-docs

Receives a status update for a previously sent message.

```APIDOC
## POST /webhook/status

### Description
Receives a status update for a message. The callback is accepted and further attempts to post it will not be taken.

### Request Body
- **message_id** (string) - Required - Message ID in the system.
- **channel** (string) - Required - Sending channel.
- **timestamp** (string) - Required - Report sending time.
- **external_id** (string) - Optional - The request ID in the partner system.
- **type** (string) - Required - Enum: "status", "recipient_response".
- **status** (integer) - Optional - Message status code.
- **channel_additional_data** (object) - Optional - Additional data concerning this message.

### Request Example
{
  "message_id": "ff1ca1f9-94f2-4e43-97ed-a4ca672957c1",
  "channel": "viber",
  "timestamp": "2021-04-02T15-14-30Z",
  "external_id": "messaggio-acc-external-id-0",
  "type": "status",
  "status": 100,
  "channel_additional_data": {
    "viber": {
      "session_id": "5672936410461553811",
      "message_type": "session_ongoing"
    }
  }
}

### Response
#### Success Response (200)
- Callback was accepted and further attempts to post it will not be taken.
```

--------------------------------

### Inbound message webhook payload

Source: https://messaggio.com/api-docs

JSON structure for receiving an inbound message from a user.

```json
{
  * "message_id": "703be60f-8e98-4d40-aa17-138703df6261",
  * "channel": "viber",
  * "timestamp": "2021-11-03T09-49-34Z",
  * "type": "recipient_response",
  * "recipient_response": {
    * "recipient": {
      * "phone": 35699554433
},
    * "from": "msgiotest",
    * "content": {
      * "type": "text",
      * "text": "Inbound message text"
}
}

}
```

--------------------------------

### Request payload for message status

Source: https://messaggio.com/api-docs

JSON payload required to request the status of specific message IDs via defined channels.

```json
{
  "recipients": [
    {
      "id": "073ff427-5fd3-4cde-b611-6071d75ec7eb"
},
    {
      "id": "ef1ee51d-9dc9-40e5-8914-480d14210d6c"
}
],
  "channels": [
    "sms"
],
  "sms": {
    "from": "EmptyTest"
}

}
```

--------------------------------

### Message status update webhook payload

Source: https://messaggio.com/api-docs

JSON structure for receiving updates regarding the delivery status of a message.

```json
{
  * "message_id": "ff1ca1f9-94f2-4e43-97ed-a4ca672957c1",
  * "channel": "viber",
  * "timestamp": "2021-04-02T15-14-30Z",
  * "external_id": "messaggio-acc-external-id-0",
  * "type": "status",
  * "status": 100,
  * "channel_additional_data": {
    * "viber": {
      * "session_id": "5672936410461553811",
      * "message_type": "session_ongoing"
}
}

}
```
Tokens:
Raw