Source API
With the Source HTTP API you can build your own Airy messaging source in no time.
note
This feature is disabled by default. To enable it you need to provide values for the security.jwtSecret
, security.systemToken
and integration.source-api.enabled
fields in your airy.yaml config.
The source API allows you to leverage Airy's message ingestion and real time delivery for any messaging platform that is not yet officially supported. This is a typical usage pattern:
- Get a source access token
- Create a channel
- Forward incoming events to Airy
- Handle outgoing messages or changes in metadata by registering an action endpoint
Note For Airy there exists a 1 to 1 mapping between a source's channel/conversation/message id to the one stored in Airy. Therefore, the ids referenced in this payload must be identifiers used by the source.
Take for instance the Facebook Messenger source. You should map these fields like so:
source_id
β This is the identifier that will be written to all your messaging data (i.e. thesource
field on every message) and should thus not be changed later unless you want to partition your data.source_message_id
β themid
sent in every webhook message event. If your messaging source does not provide message ids, you can either create them yourself or use something like the hash of the message content and the timestamp as a proxy.source_channel_id
β For Messenger this is the Facebook page id. If your source only supports one channel per account, you can also use a constant value for this field.source_conversation_id
β Contacts for each Facebook page in Messenger are identified by a Page-scoped ID. Since in Messenger page conversations cannot have multiple participants, this uniquely identifies a conversation.
#
Managing sourcesUsing your user authentication you create, read, update, and delete sources.
#
Create a sourcePOST /sources.create
To ensure that apps using the source API can write their data in isolation of each other, every app receives a
JWT which encodes the source id. This JWT has to be set on the Authorization
header of each request to authenticate
the source and write the correct identifier to the messaging data.
Sample request
source_id
An unique identifier of your source that will be stored alongside all messaging data.action_endpoint
(optional) If your source app should handle events such as outbound messages, you need to specify the action http endpoint here.name
(optional) Human readable name for this source.image_url
(optional) Icon presenting this source for display.
Sample response
#
List sourcesPOST /sources.list
Sample response
#
Delete a sourcePOST /sources.delete
Responds with 202 (Accepted)
.
Sample request
#
Update a sourcePOST /sources.update
Sample request
Sample response
#
Manage source channelsUsing the token obtained during creation a source can manage its own channels using the following endpoints.
#
Create a channelCreates a channel for the authenticated source.
POST /sources.channels.create
Sample request
source_channel_id
source identifier of the channel. Messages sent to/sources.webhook
must have a connected channel.token
(optional) You can include a token and other keys in the metadata to make it easier to build stateless source apps.
Sample response
#
List channelsList all connected channels of the authenticated source.
POST /sources.channels.list
Sample response
#
Disconnect a channelReturns a 403
if the source does not have access to the given channel_id
POST /sources.channels.disconnect
Sample request
Empty response (204)
#
Inbound WebhookYou can use this endpoint to ingest (inbound) messages and metadata into Airy. Not to be confused with the (outbound) Webhook API.
POST /sources.webhook
Sample request
#
Action endpointWhen you create a source you can register an action endpoint. This way Airy will be able to map common messaging features to your source. The endpoint will be called with a POST
request containing a JSON payload that will indicate, which action to perform. Each action requires a different response. See below for possible action payloads, and their expected responses.
Each request includes an X-Airy-Content-Signature
header that should be used to validate the authenticity of the request. To do so, compare the signature against the SHA256 HMAC of the source token you obtained during creation with the request content. Pseudocode:
#
Send messageWhen Airy users call the /messages.send
endpoint to send a message to a conversation linked to your source, Airy will call your action endpoint with the following payload. Depending on the outcome you must respond with either a success or a failure payload.
The conversation object is absent if there is no existing conversation. If your source does not support sending messages to new conversations, you should respond with a failure message.
warning
It's possible for users to send messages to your source before it was connected and before this API was installed in the cluster. In that case messages with older send_at
timestamps can be sent. It is up to your source to decide when a message is too old to send and return an error.
Success response payload
Status code must be 200
.
Failure response payload
Status code must be in the range of 4xx
. For status codes above 500
the response Airy considers the network request failed, and the source unreachable.