The message API allows you to programmatically send Zinc messages to people or groups. You can create automated systems that notify people or groups in Zinc when different events occur. Any system that can be configured to send an HTTP request in response to an event can push information into Zinc. Or you can write custom code that sends a message in Zinc based according to unique business logic.
How Does it Work?
The message API allows you to send HTTP POST requests containing all of the information needed to create a Zinc message. These can be addressed to individuals or groups. The message data is sent as a JSON payload in the request body.
To use the message API you need to create a message bot tied to an official group. You can do this on the group settings screen. The bot has a unique ID for receiving and forwarding HTTP message requests. Messages sent via the bot’s HTTP endpoint will appear in Zinc conversations as coming from the bot.
The bot is associated with an official group, and if you do not explicitly specify any recipients in the request body it will deliver messages to that official group. However you can optionally override this behavior by specifying a list of email addresses of Zinc users in the request body. If you do so, the bot will deliver the message to those individuals in an ad hoc conversation.
Who Can Send Messages?
Anyone who knows the message bot’s unique API endpoint URL can send a message via that bot. These endpoints are just like Notification Bot email addresses. They contain an unguessable string of random characters to keep them unique and private, but anyone who does know the URL can send messages via the bot.
Is there a limit on the number of messages that can be sent?
No. There is no limit. You can send as many messages as you want via the message API.
Message data is sent via a JSON body in an HTTP request with the method POST. The request body must contain a “body” attribute, containing the message body. It can optionally contain a “recipients” attribute pointing to an array of email addresses. Including an array of recipients will override the default behavior of sending messages to the official group the bot is associated with.
"body": "hello world."
This will send a message with the text “hello world” to the group associated with the message bot with the identification token specified in :id.
This will send a message containing the text “hello world” to the Zinc users “firstname.lastname@example.org” and “email@example.com”. Note: only users who belong to the same organization as the bot will be added to the ad hoc conversation and receive the message. Addresses of users who are not in the bot's organization will be ignored.
Finding the Message Bot Identification Token
To use the messaging API, you will need to specify the id of the bot from which the message is being sent. To do this you must first create a bot. Once you have created a bot, copy the prefix of its auto-generated email address, as shown below. This is the identification token that you will use in place of the :id mentioned above.