Arkipel Message Specifications

This section documents all message types supported by Arkipel communities. Each message type includes:

  • Description
  • Request schema
  • Request attributes
  • Response schema

Global Request Attributes (for all messages)

  • payload.type (Message Type)
  • signature
  • source_public_key

NOTE: In the request and response examples, only the minimum required attributes are shown, except otherwise

Search Request Attributes (for query messages)

Inside a payload.q hash:

  • per_page - Integer - How many records to be returned per page
  • page - Integer - Page number to be returned

Search Response Attributes (for query messages)

Inside a payload.q hash:

  • per_page - Integer - How many records returned per page
  • page - Integer - Page number returned
  • total - Integer - Total records count

Queries (Read Operations)

Distributions

Status Message Type Description Documentation
❌ distributions:query Retrieve a list of distributions. View
📅 distribution:query Retrieve a single distribution by ID. View

Distribution Templates

Status Message Type Description Documentation
✅ distribution_templates:query Retrieve a list of distribution templates. View

Forms

Status Message Type Description Documentation
✅ forms:query Retrieve a list of forms supported by the community. View
✅ form:query Retrieve a single form by ID. View

Households

Status Message Type Description Documentation
✅ households:query Retrieve a list of households. View
✅ household:query Retrieve a single household by ID. View

Household Categories

Status Message Type Description Documentation
✅ household_categories:query Retrieve a list of household categories. View

People

Status Message Type Description Documentation
✅ people:query Retrieve a list of people. View
✅ person:query Retrieve a single person by ID. View

Person Categories

Status Message Type Description Documentation
✅ person_categories:query Retrieve a list of person categories. View

Mutations (Write/Destroy Operations)

Addresses

Status Message Type Description Documentation
📅 address:delete Delete a single address by ID. View

Contact Informations

Status Message Type Description Documentation
📅 contact_information:delete Delete a single contact information by ID. View

Distributions

Status Message Type Description Documentation
🚧 distributions:upsert Create a distribution or update a single distribution by ID. View
❌ distribution:delete Delete a single distribution by ID. View

Forms

Status Message Type Description Documentation
📅 form:fill Fill a form. View

Households

Status Message Type Description Documentation
✅ households:upsert Create a household or update a single household by ID. View
❌ household:delete Delete a single household by ID. View
✅ household_person:delete Delete a person link to an household by ID. View

People

Status Message Type Description Documentation
✅ people:upsert Create a person or update a single person by ID. View
❌ person:delete Delete a single person by ID. View

Procurements

Status Message Type Description Documentation
📅 procurements:upsert Create a procurement or update a single procurement by ID. View
❌ procurement:delete Delete a single procurement by ID. View

System Messages

Status Message Type Description Documentation
✅ ping Check connection health. View
✅ arkipel_messages:query Query a message from a given ID View

Asynchronous Message Processing

When sending mutation messages (e.g., people:upsert, procurements:upsert), the response will not immediately include the created, updated, or destroyed resource. Instead, the message will be processed asynchronously—either queued for background processing or pending user validation.

Response Structure

The response will always include a message_id, which serves as a reference to track the status or result of the operation. You can use this message_id to query the outcome later using the arkipel_messages:query message type.

How to Retrieve Results

  1. Store the message_id from the response.

  2. Query the status by sending an arkipel_messages:query message with the message_id:

    {
  "type": "arkipel_messages:query",
  "message_id": "6916452112f746b2b4cf48c1"
}
  3. The response will include the final state of the operation (e.g., success, failure, or pending).

Why This Approach?

  • Decoupling: Allows for background processing, user validation, or delayed execution.
  • Reliability: Ensures integrators can always retrieve the result, even if processing takes time.

Key Points to Highlight

  • Asynchronous by Design: Mutations are not blocking; the system acknowledges receipt but processes them later.
  • Tracking: The message_id is your reference to poll or subscribe for updates.
  • Idem-potency: The same message_id can be queried multiple times for consistency.

Sequence Diagram

Glossary

Message Implementation Status

Emoji Status Meaning
✅ Implemented Message is fully implemented
🚧 In Progress Currently being worked on
❌ Not Implemented Not started or not planned yet
📅 Planned Scheduled for future implementation
🗑️ Deprecated Message is deprecated