Skip to content

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)