Connectly Documentation
  • 👋Welcome to Connectly.ai
  • 🚀Quick Start
    • Prerequisites
    • Authentication
    • Send WhatsApp template message
    • Send WhatsApp session message
  • 📣Campaigns
    • Campaign Sendout
      • Send Campaigns
  • 🤖Sofia AI
    • How to use Sofia AI?
    • Sofia AI API
      • Reference
        • Core Concepts
        • sales_assistant_v2/invoke/v1
  • 📱Message API
    • Message Service API
      • MessageService
        • Send template message
        • Send session message
      • Error codes
    • Webhook API
      • WebhookService
        • Create a webhook registration by event topic
        • Update an existing webhook registration by event topic
        • Get webhook registrations for business
        • Delete a webhook registration for business
      • Webhook Payload
        • Delivery Status Error Codes
        • Payload Media Types
  • 🤖Business Management
    • Business Management API
      • Template Management
        • Create a template
        • Get templates
      • Quality Signals
  • 📱Integrations
    • Integrations
      • WebEngage Integration
      • Message your customers on Zendesk through Connectly
      • Message your customer on Intercom through Connectly
    • [Alpha] Moengage
      • MessageService
        • Send Campaign via API
  • 📊Analytics
    • Analytics
      • [Alpha] Campaign report
      • Reports API
        • Webhooks configuration
  • 👀FAQ
  • Migrating WhatsApp Accounts
  • How to use time delay?
Powered by GitBook
On this page
  1. Message API
  2. Message Service API
  3. MessageService

Send session message

Send a message to recipient on target channel, i.e. WhatsApp, SMS.

PreviousSend template messageNextError codes

Last updated 7 months ago

If you are trying to send a WhatsApp message and the number you are messaging has not messaged you within the last 24 hours, you will need to send a pre approved template message. See for details.

24 hour WhatsApp restriction

If the recipient has not initiated the conversation first within the last 24 hours you CAN NOT send the messages to them. In this case, you MUST use templated message API /v1/businesses/{businessId}/send/whatsapp_templated_messages.

  • Generally, you use /v1/businesses/{businessId}/send/messages to reply to the customers who already messaged you first.

  • You use /v1/businesses/{businessId}/send/whatsapp_templated_messages to initiate with the customer first.

Select the WhatsApp number you want to send from

The endpoint supports an optional sender field in the body. If you have multiple WhatsApp phone numbers with Connectly you can choose which one you want to send the message from. The payload needs to contain the optional sender object specifying the phone number in the id section and channelType as whatsapp:

{
  "sender": {
    "id": "+14151111234",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "+16044441111",
    "channelType": "whatsapp"
  },
  "message": {
    "text": "Hello, this is a text message!"
  }
}

Send a message with an attachment

You can include an attachment to the message. Currently, only a single attachment is supported.

Image Attachment Message

{
  "sender": {
    "id": "+14151111234",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "+16044441111",
    "channelType": "whatsapp"
  },
  "message": {
    "attachments": [
      {
        "type": "image",
        "url": "https://example.com/image.jpg",
        "caption": "Check out this image!"
      }
    ]
  }
}

Video Attachment Message

{
  "sender": {
    "id": "+14151111234",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "+16044441111",
    "channelType": "whatsapp"
  },
  "message": {
    "attachments": [
      {
        "type": "video",
        "url": "https://example.com/video.mp4",
        "caption": "Check out this video!"
      }
    ]
  }
}

Audio Attachment Message

{
  "sender": {
    "id": "+14151111234",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "+16044441111",
    "channelType": "whatsapp"
  },
  "message": {
    "attachments": [
      {
        "type": "audio",
        "url": "https://example.com/audio.mp3"
      }
    ]
  }
}

Document Attachment Message

{
  "sender": {
    "id": "+14151111234",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "+16044441111",
    "channelType": "whatsapp"
  },
  "message": {
    "attachments": [
      {
        "type": "document",
        "url": "https://example.com/document.pdf",
        "caption": "Check out this document!",
        "filename": "document.pdf"
      }
    ]
  }
}

Send location message

{
  "sender": {
    "id": "+14151111234",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "+16044441111",
    "channelType": "whatsapp"
  },
  "message": {
    "location": {
      "latitude": 37.7749,
      "longitude": -122.4194,
      "name": "San Francisco",
      "address": "123 Main St"
    }
  }
}

Send interactive list message

{
  "sender": {
    "id": "+14151111234",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "+16044441111",
    "channelType": "whatsapp"
  },
  "message": {
    "listMessage": {
      "header": {
        "text": "Check out this list of items!"
      },
      "footer": {
        "text": "Choose an option from the list."
      },
      "button": {
        "text": "Select"
      },
      "sections": [
        {
          "title": "Section 1",
          "rows": [
            {
              "id": "1",
              "text": "Item 1",
              "description": "Description for Item 1"
            },
            {
              "id": "2",
              "text": "Item 2",
              "description": "Description for Item 2"
            }
          ]
        },
        {
          "title": "Section 2",
          "rows": [
            {
              "id": "3",
              "text": "Item 3",
              "description": "Description for Item 3"
            }
          ]
        }
      ]
    }
  }
}

Send interactive reply buttons message

{
  "sender": {
    "id": "+14151111234",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "+16044441111",
    "channelType": "whatsapp"
  },
  "message": {
    "text": "This is a reply button message",
    "replyButtonMessage": {
      "header": {
        "text": "Header"
      },
      "footer": {
        "text": "Footer"
      },
      "buttons": [
        {
          "id": "b1",
          "text": "Button 1"
        },
        {
          "id": "b2",
          "text": "Button 2"
        },
        {
          "id": "b3",
          "text": "Button 3"
        }
      ]
    }
  }
}

Header Media

Both list and quick reply messages use the same header parameter structure. Here is an example of an image header:

"header": {
    "attachment": {
        "type": "image",
        "url": "https://cdn.connectly.ai/26fa/26fa1308-d328-41c9-a6a1-d5f4225a3768",
    }
},

This is an example of a document header with a filename:

"header": {
    "attachment": {
        "type": "document",
        "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
        "filename": "feeeelsss"
    }
},

Use list_message to send a WhatsApp interactive list message. For more information, see .

Use reply_button_message to send interactive reply button message. For more information, see .

📱
WhatsApp documentation
WhatsApp documentation
here
  • POST/v1/businesses/{businessId}/send/messages
  • 24 hour WhatsApp restriction
  • Select the WhatsApp number you want to send from
  • Send a message with an attachment
  • Send location message
  • Send interactive list message
  • Send interactive reply buttons message
  • Header Media
post

API to send a message to recipient on target channel, i.e. WhatsApp, SMS

Authorizations
Path parameters
businessIdstringRequired
Body
campaignNamestringOptional

Optional. Campaign name.

Example: test_campaign_2022-03-12
Responses
200
A successful response.
application/json
201
Successful response containing id of created message.
application/json
default
An unexpected error response.
application/json
post
POST /v1/businesses/{businessId}/send/messages HTTP/1.1
Host: 
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1868

{
  "sender": {
    "id": "+16502223333",
    "channelType": "channel_type_unspecified",
    "name": "John Snow"
  },
  "recipient": {
    "id": "+16502223333",
    "channelType": "channel_type_unspecified",
    "name": "John Snow"
  },
  "message": {
    "id": "01FPW47QF69Y5JZH24605VAKQB",
    "text": "text",
    "attachments": [
      {
        "type": "attachment_type_unspecified",
        "url": "https://cdn.connectly.ai/d9c4/d9c45701-4895-4b19-8173-dd6a013ae981",
        "caption": "text",
        "filename": "text"
      }
    ],
    "location": {
      "latitude": 1,
      "longitude": 1,
      "name": "text",
      "address": "text"
    },
    "isEcho": true,
    "listMessage": {
      "header": {
        "text": "text",
        "attachment": {
          "type": "attachment_type_unspecified",
          "url": "https://cdn.connectly.ai/d9c4/d9c45701-4895-4b19-8173-dd6a013ae981",
          "caption": "text",
          "filename": "text"
        }
      },
      "footer": {
        "text": "text"
      },
      "button": {
        "id": "text",
        "text": "text"
      },
      "sections": [
        {
          "title": "text",
          "rows": [
            {
              "id": "text",
              "text": "text",
              "description": "text"
            }
          ]
        }
      ]
    },
    "replyButtonMessage": {
      "header": {
        "text": "text",
        "attachment": {
          "type": "attachment_type_unspecified",
          "url": "https://cdn.connectly.ai/d9c4/d9c45701-4895-4b19-8173-dd6a013ae981",
          "caption": "text",
          "filename": "text"
        }
      },
      "footer": {
        "text": "text"
      },
      "buttons": [
        {
          "id": "text",
          "text": "text"
        }
      ]
    },
    "singleProductMessage": {
      "footer": {
        "text": "text"
      },
      "catalogId": "text",
      "productItem": {
        "productRetailerId": "text"
      }
    },
    "multiProductMessage": {
      "header": {
        "text": "text",
        "attachment": {
          "type": "attachment_type_unspecified",
          "url": "https://cdn.connectly.ai/d9c4/d9c45701-4895-4b19-8173-dd6a013ae981",
          "caption": "text",
          "filename": "text"
        }
      },
      "footer": {
        "text": "text"
      },
      "catalogId": "text",
      "sections": [
        {
          "title": "text",
          "productItems": [
            {
              "productRetailerId": "text"
            }
          ]
        }
      ]
    },
    "referral": {
      "sourceUrl": "text",
      "sourceId": "text",
      "sourceType": "text",
      "headline": "text",
      "body": "text",
      "mediaType": "text",
      "imageUrl": "text",
      "videoUrl": "text",
      "thumbnailUrl": "text",
      "ctwaClid": "text"
    }
  },
  "campaignName": "test_campaign_2022-03-12",
  "order": {
    "parentId": "text",
    "strategy": "strategy_unspecified"
  }
}
{
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
}