Sending Communications from a Workflow

Overview

You can trigger a communication to a gaiia entity — such as an account, user, or commercial account — directly from a workflow using a custom communication template. When this step runs, gaiia checks the entity's communication preferences, picks the right channel (email, SMS, or both), and hands the message off for delivery automatically.

In this article, we'll be covering how to set up a workflow step that sends a communication, what each input controls, and how to interpret the response.

Understand how it works

Before sending anything, gaiia performs a series of checks:

• It looks up the entity you specified and retrieves its communication preferences, including which channels are enabled and what language it uses.
• It finds the template you referenced and checks whether a variation exists for the entity's language.
• It confirms that at least one enabled template variation matches a channel the entity has turned on (email or SMS).
• It verifies that the necessary contact information (email address or phone number) is on file for the channels being used.
• If all checks pass, gaiia passes the message to the notification service and records a delivery history entry.

A successful response means the message was accepted for delivery — not that it has been delivered yet. Whether the message ultimately reaches the recipient is tracked separately in notification history and is not reflected in the workflow step's response.

If any check fails, the step returns an error code and no message is sent. The workflow continues normally — these are expected outcomes, not failures that stop execution.

Set it up

Add a gaiia GraphQL node to your workflow. The node has two input sections: Query and Variables. Use the Query section for the mutation itself and the Variables section to pass in dynamic values from your gaiia data.

The mutation accepts four inputs:

1. Entity — the GlobalID of the entity receiving the communication. Supported types: Account, CommercialAccount, PropertyGroup, PropertyGroupManager, User. Archived entities are treated as not found.
2. Template — the GlobalID of the custom communication template to use.
3. Importance (optional) — delivery priority. HIGH for prioritized delivery, DEFAULT for standard. Omitting this defaults to standard.
4. Description (optional) — a free-text label attached to the delivery record, up to 1,000 characters. Useful for identifying what triggered the send when reviewing communication history.

Example

Here is a working example of how you'd send communications using the gaiia GraphQL API node, assuming the workflow has a Manual trigger on an object. 

You can copy the following into the Query and Variables sections of the node. Update the values in the Variables section to match your workflow's data.

Query

mutation SendCommunication($entityId: GlobalID!, $templateId: GlobalID!) {
  sendCommunication(
    input: {entity: {id: $entityId}, template: {fromCustomCommunicationTemplateId: {templateId: $templateId}}}
  ) {
    errors {
      message
      code
    }
  }
}

Variables

const inputFunction: NodeStateFunction = ({ secrets, state, utils, variables }) => {
  return {
    entityId: state.objectId,
    templateId: 'custom_communication_template_vRe9UrXSw5Yj6v6jsAc5VG'
  };
};

A successful response returns an empty errors array, indicating the message was accepted for delivery. If a pre-flight check fails, one error object is returned with a code and message — and no message is sent.

Understand error responses

When a pre-flight check fails, the response includes one of the following error codes. These do not throw an exception or stop workflow execution — the step resolves normally and returns the error in the errors field.

• ENTITY_NOT_FOUND — The entity GlobalID doesn't match any active record, or the entity has been archived.
• TEMPLATE_NOT_FOUND — The template GlobalID doesn't match any custom template available in that environment.
• NO_TEMPLATE_VARIATION_ENABLED — The template exists, but no enabled variation is available for the entity's language. Check that a variation has been created and enabled for that language in your template configuration.
• NO_MATCHING_ENTITY_PREFERENCE_FOR_CHANNELS — The entity has disabled all channels (email and SMS) that have an enabled template variation. At least one of the entity's enabled channels must match an available variation.
• NO_CONTACT_INFO — The entity has a channel enabled, but no corresponding contact information on file (no email address for email, no phone number for SMS).

We recommend reading the errors field in your workflow output to handle these cases explicitly — for example, by branching to a fallback step using a Condition node when an error code is present.