With the Source HTTP API you can build your own Airy messaging source in no time.
This feature is disabled by default. To enable it you need to provide values for the
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. the
sourcefield on every message) and should thus not be changed later unless you want to partition your data.
midsent 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.
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.
source_idAn 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.
Using the token obtained during creation a source can manage its own channels using the following endpoints.
Creates a channel for the authenticated source.
source_channel_idsource identifier of the channel. Messages sent to
/sources.webhookmust 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.
List all connected channels of the authenticated source.
403 if the source does not have access to the given
Empty response (204)
You can use this endpoint to ingest (inbound) messages and metadata into Airy. Not to be confused with the (outbound) Webhook API.
When 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:
When 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.
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
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.