What are messages?

A user or an app can send a message either to another user or to a group. One can send both plain text messages and messages with rich content. Plain text messages display the sender name, the user avatar, the text of the message, and the time at which it was sent. 

On the other hand, messages with rich content (formally referred to as attachments) can show widgets, FlockML, images, buttons, and provide files to download, among other things. See Sending Attachments for more details.

What can I use Messages for?

  • Send notifications to a user or a group e.g. the ToDo app sends a notification whenever a ToDo is added, updated or deleted in the group.
  • Send attachments on behalf of a user like the Code Snippets or the Notes app
  • Converse with your users using your app's bot. For eg the Reminder app bot sends a message to a user based on the user's configuration

What are the types of Messages?

Your app can send messages either –

  1. Inline within a one-on-one or group chat tab. You may wish to do this for messages that are meant to be seen by the entire group or both parties in a one-on-one conversation. For eg the Todo app sends a notification to the entire group when a Task created within that group was completed.
  2. Directly to a user from your app's Bots. This message will appear in your Bot's chat tab for that user. You may wish to do this for messages that are meant only for a given user e.g. the Reminder app bot sends a notification directly to a user

How can my app send messages into Flock?

Your app can send messages via the chat.sendMessage method. Prior to that, however, you will need to create an app.

  1. Go through Creating an App to set up your app via the developer dashboard.
  2. Install the app into your own Flock account. Make sure that you save the authentication token received in the app.install event. You will need it for the method calls that follow.

  3. To be able to send a message to a contact or a group, you will need to know their identifier first. The methods roster.listContacts and groups.list can help you do this. Typically, your configuration URL will use these methods to set up an interface wherein a user can select which contact or group he wants to send messages from your app to.

  4. Send this message using the chat.sendMessage method. You can use either HTTP GET:

    chat.sendMessage using a GET request
    https://api.flock.co/v1/chat.sendMessage?to=u:513a9f4ae409&text=hello&token=632542db-1a23-4e06-8b39-01f8b0868d57

    or POST to call the method.

    chat.sendMessage using a POST request
    POST /v1/chat.sendMessage HTTP/1.1
Host: api.flock.co
Content-Type: application/x-www-form-urlencoded
Content-Length: 70

to=u:513a9f4ae409&text=hello&token=632542db-1a23-4e06-8b39-01f8b0868d57
  5. If you want to send attachments, take a look at the Sending Attachments page. Or if you want to create a bot, take a look at Bots.