Page History

...

Each app optionally gets its own bot. Bots have a name and an avatar, and you can use them to send and receive messages to and from your users.

What can I use a bot for?

What you use a bot for is limited only by your imagination:

• A reminder app can use a Reminder bot to send reminders
• A travel bot can let users search for and book flights through chat
• You can create a support bot to receive questions and provide answers to users

How do I get a bot for my app?

You can enable your app's bot during the app creation process in the Advanced info section. You will see your bot's identifier and bot token on enabling your Bot. Any messages sent to your app's bot will be sent at this identifier. You can use the token to make method calls on behalf of the bot e.g. sending messages to a user.

How do I set my

...

bot's name and

...

avatar?

Your bot will automatically assume your App's name followed by "Bot" and your App's icon as its default avatar

How will my

...

app's bot be visible to my users?

Once you enable your bot, any users who install or have installed your app will see your app's bot in their contact list.

How do I send and receive messages using bots?

You can send a message using the chat.sendMessage method. Authenticate the method call using your bot's token.

// POST https://api.flock.co/v1/chat.sendMessage {
    "message": {
        "to": "<recipient identifier>",
        "text": "<message text>"
    }
}HTTP/1.1
Host: api.flock.co
Content-Type: application/x-www-form-urlencoded
Content-Length: 70
 
to=u:<user>&text=hello&token=<bot token>

To receive a message, listen for the chat.receiveMessage event on your app service your event listener URL.

{
    "name": "chat.receiveMessage",
    "message": {
        "from": "<sender identifier>u:<user>",
        "to": "<bot identifier>u:<bot>",
        "text": "<message text>hello"
    }
}

Anchor
Channel Channel

Can a

...

bot join a

...

No.

channel and send messages to it?

Bots cannot join channels, but they can send messages to it. While calling chat.sendMessage, set to to the channel id, and token to the bot token.

You also need to set onBehalfOf to the id of a user who has installed the app, is a member of the channel and has permission to post messages to it. Since bots cannot join channels themselves, the user whose id is provided in onBehalfOf is used to check for channel membership and posting permissions. This means that an app's bot can only post messages to channels where at least one user who has installed the app has permission to post messages.

POST /v1/chat.sendMessage HTTP/1.1
Host: api.flock.co
Content-Type: application/x-www-form-urlencoded
Content-Length: 70
 
to=g:<channel>&text=hello&token=<bot token>&onBehalfOf=u:<user>