SendMessage API

You can send text, image, video, voice, file and structured messages to your users by using SendMessage API.

Request URI#

https://<DIYALOG-SERVER-API-ENDPOINT>/v1/bots/v1/bots/sendmessage/<YOUR-BOT-ACCESS-TOKEN>

DIYALOG-SERVER-API-ENDPOINT : It is the api endpoint address of the DLG server. We can give api.dlgmessenger.com as an example.

YOUR-BOT-ACCESS-TOKEN : You can only send all type of messages to you users via bot user that created by admin of the platform. If you want you can send messages to your users from all of your applications via one bot, or you can send them via different bots regarding as your applications functionality. The user will seee the bot that created for you as a standart user in their mobile or web clients. You can do messaging via this bot. Every created bot has an unique access token. You should take it from the DLG admin and add it to the end of the SendMessage api uri request. When DLG server receive your api request, it will get token from the request and check it and find the bot information. Then It send your message to the user as if this bot user.
This token is an access token and it should be private and store safely. If it can be accessed by unauthorized people, they can send message to your users as you. Therefore it should be store safely.

Example Request#

You can see below as an example http request that can run with curl command.

curl -X POST -H "Content-Type: application/json" -d '{
    "recipient":    {
        "appCustomerId":"1231231"
    },
    "message":{
        "text":"hello world",
        "messageId": "msg-id-123-112233"
        "quick_replies":[]
    }
}' "https://api.dlgmessenger.com/v1/bots/sendmessage/c2dc9bf3e0c3218e9ab22b56002e4644"

Easyly seen in the request, https://api.dlgmessenger.com/v1/bots/sendmessage/c2dc9bf3e0c3218e9ab22b56002e4644 is the URI of the request. It can be also seen that an JSON obejct is is sending with POST method in the curl command.

If we analyse the endpoint address;
Api Server : api.dlgmessenger.com
Api Name : /v1/bots/sendmessage/
Bot Token : c2dc9bf3e0c3218e9ab22b56002e4644

Request Details#

Api request has two properties. Both of these properties are objects that has self properties. recipient is object that define the recipient of the message and message is another object that define the content of the message.

Property	Type	Description	Mandatory
recipient	Object	recipient object	Yes
message	Object	Content of the message - (message object)	Yes

The JSON that has two object defined in the above should be send to server with POST method.

{
  "recipient":{
    ...
  },
  "message":{
    ...
  }
}

recipient#

You can pass the user information you want to send the message to api in the recipient object.

Property	Type	Description	Mandatory
appCustomerId	String	Customer id in your system	Optional
appStaffId	String	Your staff id.	Optional
id	String	Unique DLG user id.	Optional

You can pass the the user information that will receive your message with this object. Your request should only have one of the properties that appCustomerId, appStaffId or id.

There are two unique id for a single user in the DLG platform One of them is DLG user id. This id is created randomly when user registering to the system. Besides of this id, according to the user type, one of the customer id or staff id are stored for the user in DLG.

As a result, you can use one of the customer id or staff id and DLG id in order to send message.

If you know the DLG user id, you can use it for customor or staff.

Using customer id and staff id is more applicable than using DLG user id. Because if you want to use DLG id, you should store all DLG user ids in your system.

Sample recipient json object#

{
  "recipient": {
    "appCustomerId": "123456789"
  },
  "message": {
  ...
  }
} 

message#

You should use message object for setting content of the message.

message includes by text, attachment, quickReplies, quickRepliesV2 properties. A message object can only have one of the text or attachment.

You should only use text property, when sending text message to your users. For other type of message like media, image, picture, video, audio, file or template message, you should use attachment instead of text.

You can add quick reply buttons to you messages by setting quickRepliesV2 property.

Sample message json object#

{
  "recipient": {
    ...
  },
  "message": {
    "messageId" : "msg-id-123-1122-1111",
    "text" :"hello world ¯\_(ツ)_/¯",
    "quickReplies" : [],
    "quickRepliesV2" : []
  }
}

Property	Type	Description	Mandatory
messageId	String	This is a unique id of your message. You should create it in your system and send it to api. If you don't create and sent it to api DLG will create it for you and send it to you in the response of your request. DLG platfrom will feed the events of the messages to your system by this id. You can use it to differenciate events by this id. Therefore, this id is important for following all events of your message by your system.	Optional
text	String	Text that will send to your user. You should only use text property, when sending text message to your users.	Optional
attachment	Object	(attachment Object) Contents of message types other than text can be set with this property.	Optional
quickReplies	Array<quickReply>	This field is the old version, but since it is mandatory, it should be added to all requests as empty array like "quickReplies": [] .	Yes
quickRepliesV2	Array<quickReplyV2>	New version of quickReplies property. You can use this property to add quick reply buttons to your text message.	Yes

Note :

quickRepliesV2 is the new version of the quickReply property. New DLG mobile sdk is using new version of it. Therefore you should use it to add quick reply buttons to your message. But you should also need to add empty quickReplies property for each request due to mandatory property. Also you shhould add empty quickRepliesV2 property, although you don't want to add any button.

If you don't add any of quickReplies or quickRepliesV2 property, you will receive malformed request error from DLG server.

You can see sample json object that is created for sending text message in below. DLG server will send hello worldtext message to customer whose id is 123456789

{
  "recipient": {
    "appCustomerId": "123456789"
  },
  "message": {
    "messageId" : "msg-id-123-1122-1111",
    "text" :"hello world",
    "quickReplies" : [],
    "quickRepliesV2" : []
  }
}

attachment#

If you want to send message types other than text, you should set attachment instead of text.

By setting attachment property, you can send following types of message;

Media messages : image, picture, audio, video and file
Template messages : generic template, button template

Property	Type	Description	Mandatory
type	String	This property can be one of the following values : "template""image", "audio", "video", "file"	Yes
payload	Object	Content of the attachement. payload object.	Yes

Response#

Successful API requests return the json object with the answer code http-2XX.
Response JSON object will have recipient id and message id properties. Recipient id will be the DLG user id. And message id will be the message id that is given with the request. If the request has not have any message id, DLG will create a message id and add it to response.

Response Details#

Property	Type	Description
recipient_id	String	DLG user id.
message_id	String	It is the id of the message sent to the user. If you have given a messageId in the request, this id will be sent back to you in this field. If you have not provided an id, the unique id created in the DLG system returns from this field.

Sample response

{
   "recipient_id": "2074022437",
   "message_id": "-7523925115459309081"
}