messages.send

Send a message to another connected business on Economico, including support messages. This queues delivery to the recipient; use only on the user’s instruction.

What it does

Send a message to a business this one has a relationship with on Economico, named as a party in these books. Today that relationship is the Economico service agreement, so this is how an agent files a support request (something is broken, unclear or you are stuck) or a feature suggestion (something Economico cannot do yet) with the Economico team: omit to and it goes to Economico. A demo business writes to Economico only, with topic support or feature_suggestion, a few times a day at most, and gets no reply.

Reply to a message you received with inReplyTo (the recipient, topic and a Re: subject follow from it), and point at the documents it concerns — an invoice, a statement, an agreement — with about; the recipient’s books find their own copy by content. The message is recorded in this business’s history with status sent (queued) and delivered into the recipient’s books, whose owners are emailed; its record then says delivered, or undeliverable with the reason, so report delivery only once it does.

Describe the problem in your own words with the context needed to act; never include secrets or credentials, because the message is kept permanently in both businesses’ histories.

Before you send it

An authorized OAuth connection may call it, including a headless client. Effective membership, application grant and token permissions still apply. Describe messages.send through GET /v1/catalog/commands/{name} before acting.

This command does not accept source_document_id in its envelope. Any input evidence requirements remain as documented below.

Inputs

Put these fields inside the envelope’s input object. The outer envelope names the command, a stable idempotency_key and effective_at; request and recovery rules explain those separately. Use exact minor-unit integer strings for monetary fields. Take existing IDs from prior reads or command results; choose a new identity only where the command asks for one.

Required means required within its containing object; an optional parent can be omitted.

After acceptance

When the command emits events, its documented effects and receipt are recorded in the command transaction. The response returns commandId, replayed, the command-specific result below and emitted events with their IDs and CIDs. A command is not automatically a cash movement or revenue recognition: use the behavior above to determine what this command records.

Inspect result and the affected records or reports before continuing. Save returned identifiers for later calls. Fetch GET /v1/commands/{id} with commandId to recover the accepted receipt; retry the same intent with the same idempotency key if the response was lost. Some commands can succeed with events: [] and return a transient result and commandId without persisting a receipt. A lookup of that ID can return null; retain the returned result and verify the affected record. Retrying can re-evaluate the current state rather than replay a stored result. A domain no_change is a separate success outcome with no persisted receipt.

Result fields

Required means required within its containing object; an optional parent can be omitted.

All commands · Operation and errors · Reusable schemas

Keep credentials out of prompts; rehearse writes only in a disposable sandbox.

Exact request schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "const": "messages.send"
    },
    "input": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "to": {
          "type": "string",
          "minLength": 1,
          "description": "The recipient's party id in these books; it must be a party this business holds a platform-bound agreement with. Omit it to write to Economico (the only recipient a demo business has; the result then names no party)."
        },
        "topic": {
          "enum": [
            "support",
            "feature_suggestion",
            "general"
          ],
          "description": "support: something is broken, unclear or you are stuck. feature_suggestion: a capability Economico does not have yet. general: anything else."
        },
        "inReplyTo": {
          "type": "string",
          "minLength": 1,
          "description": "The id of a message this business received. The reply goes to its sender; topic and subject default from it."
        },
        "about": {
          "type": "array",
          "maxItems": 10,
          "items": {
            "type": "string",
            "minLength": 1
          },
          "description": "Document ids in these books the message is about, such as an invoice you received."
        },
        "subject": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "body": {
          "type": "string",
          "minLength": 1,
          "maxLength": 5000
        },
        "context": {
          "type": "object",
          "maxProperties": 20,
          "propertyNames": {
            "minLength": 1,
            "maxLength": 64
          },
          "additionalProperties": {
            "type": "string",
            "maxLength": 500
          },
          "description": "Optional structured detail about what you were doing, such as the tool or workflow you attempted."
        }
      },
      "required": [
        "body"
      ]
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "effective_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
    }
  },
  "required": [
    "name",
    "input",
    "idempotency_key",
    "effective_at"
  ],
  "additionalProperties": false
}

Accepted command receipt

{
  "type": "object",
  "required": [
    "commandId",
    "replayed",
    "result",
    "events"
  ],
  "properties": {
    "commandId": {
      "type": "string"
    },
    "replayed": {
      "type": "boolean"
    },
    "imported": {
      "const": true,
      "description": "The command's events are history from before the business joined Economico, recorded as an import: free of monthly events."
    },
    "result": {
      "type": "object",
      "properties": {
        "messageId": {
          "type": "string",
          "minLength": 1
        },
        "direction": {
          "enum": [
            "outbound"
          ]
        },
        "status": {
          "enum": [
            "sent"
          ]
        },
        "to": {
          "type": "string",
          "minLength": 1
        },
        "toName": {
          "type": "string"
        },
        "relationship": {
          "type": "object",
          "properties": {
            "contractId": {
              "type": "string"
            },
            "agreementId": {
              "type": "string"
            },
            "connectionId": {
              "type": "string"
            },
            "demo": {
              "const": true
            }
          }
        },
        "topic": {
          "enum": [
            "support",
            "feature_suggestion",
            "general"
          ]
        },
        "subject": {
          "type": "string"
        },
        "body": {
          "type": "string"
        },
        "context": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "about": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "cid": {
                "type": "string"
              },
              "kind": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "documentId": {
                "type": "string"
              }
            },
            "required": [
              "cid",
              "kind"
            ]
          }
        },
        "inReplyTo": {
          "type": "object",
          "properties": {
            "messageId": {
              "type": "string"
            },
            "sourceMessageId": {
              "type": "string"
            }
          },
          "required": [
            "messageId",
            "sourceMessageId"
          ]
        },
        "sentAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "messageId",
        "direction",
        "status",
        "toName",
        "relationship",
        "topic",
        "subject",
        "body",
        "sentAt"
      ]
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "cid": {
            "type": "string"
          }
        }
      }
    }
  }
}

Example request

{
  "name": "messages.send",
  "input": {
    "topic": "feature_suggestion",
    "subject": "Import CSV bank statements",
    "body": "I wanted to import last month's bank statement as CSV and found no command for it.",
    "context": {
      "tool": "documents.receive"
    }
  },
  "effective_at": "2026-09-01T00:00:00Z",
  "idempotency_key": "messages.send-example-0"
}

Example request

{
  "name": "messages.send",
  "input": {
    "inReplyTo": "msg_01J00000000000000000000000",
    "body": "Thanks — the corrected invoice is attached to our books now.",
    "about": [
      "doc_01J00000000000000000000000"
    ]
  },
  "effective_at": "2026-09-01T00:00:00Z",
  "idempotency_key": "messages.send-example-1"
}