Send/Receive Messages

Use this content when building an application that will connect to the app2app service in order to send and receive messages.

Connecting your application to the service

Navigate to the App2app service dashboard and create a destination if you don't have one. A panel titled "My Destinations" will appear showing the service API endpoint.

Destination URI

Connect your application to this endpoint using Socket IO (https://socket.io). Include the following property in the “extraHeaders” connection options:

Authorization: <based64 encoding of app-cred-user:app-cred-password>

Tuning parameters in socket.io connection URL

The following parameters can be specified in the query on the connection URL, to tune the behavior of the app2app server for that connection.

For example:

wss://e1c6dx1vme-e1pciky0o5.eu1-azure-ws.kaleido.io/api/v1?auto_commit=false&batch_size=100&read_ahead=50

Name	Default	Description
`auto_commit`	`true`	Consumer: When `false` the client must acknowledge each message by emitting a `commit` event. It is important the number of commit events matches the number of messages delivered, or delivery will stall.
`read_ahead`	1	Consumer: How many messages to stream to the app ahead of the latest commit. If processing of events is asynchronous, then processing of events might occur in parallel, while messages will always be committed in the order they are delivered. Use a simple in-memory processing queue in your app to allow ordered processing, with the performance benefit of read-ahead > 1. Only applies with `auto_commit=false`
`batch_size`	1	Producer: The maximum number of messages to include in each PKCS#7 encrypted envelope, providing a significant performance boost by reducing the overhead of the public/private key cryptography. Managed destinations only
`batch_timeout`	250	Producer: The time in milliseconds to wait for more `produce` events before sealing the batch. Managed destinations only

Sending messages

Emit a “produce” Socket IO event passing a message object parameter with the following properties:

Name	Type	Required	Description
from	string	Yes	Sender destination URI
to	string	Yes	Recipient destination URI
content	string or Buffer	Yes	Message content
signature	string or Buffer	Only when sending messages from an externally-managed destination	RSA-SHA256 signature of the message content

Optional parameters:

message key: string used for coordination and delivery confirmation
callback: function that takes two parameters:
- error: diagnostic information in string format or null if no errors were detected
- result: constant “Message sent” if the message was generated

In order to receive delivery reports, add a Socket IO listener to the event “delivery-report”. Listeners will be invoked with these parameters:

result: string containing a serialized JSON object with the following properties:

Name	Type	Description
key	string	Optional message key parameter
timestamp	number	Message transmission timestamp

Receiving messages

Emit a “subscribe” Socket IO event passing an array of destination URIs. Optional parameters:

callback: function that takes two parameters:
- error: diagnostic information in string format or null if no errors were detected
- result: constant “Subscribed” if the subscription was successful

Add a Socket IO listener to the event “message”. Listeners will be invoked with these parameters:

Parameter order	Type	Description
1 (message)	string	When recipient is a Kaleido managed destination: Serialized JSON object containing the message When recipient is an externally managed destination: PKCS7 PEM containing the encrypted message
2 (key)	string	Optional message key set by the sender
3 (timestamp)	number	Message transmission timestamp (number)