> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worldvisagroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration conditions

> Choose which provider integration sends a notification based on subscriber, context, and workflow data.

Integration conditions let you choose which integration sends a message when you have more than one active integration on the same channel. For example, you might send email for one tenant through their own SendGrid account, and send everyone else's email through your default provider.

Integration conditions only pick the provider. They don't decide whether a step runs. If you want to skip a step, use [step conditions](https://docs.worldvisagroup.com/developers/workflow/add-and-configure-steps/step-conditions.md).

Some common reasons to use them:

* Each tenant has its own email or SMS provider account.
* You use different sender credentials for different locales or subscriber plans.
* A chat connection, such as Slack or Teams, should only receive messages for a specific tenant.

## Add conditions in the dashboard

1. Go to **Integrations** and open an integration, or add a new one.
2. In the side panel, click **Integration conditions**.
3. Add your rules using **AND** and **OR** groups, then click **Done**.
4. Save the integration.

The rule builder is the same one used for [step conditions](https://docs.worldvisagroup.com/developers/workflow/add-and-configure-steps/step-conditions.md#how-the-condition-builder-works), so you can nest groups and use the same operators, such as equals, contains, in, and is empty.

> [!NOTE]
>
> An integration with conditions can't be the primary integration. Saving conditions removes the primary flag, and marking an integration as primary removes its conditions. For email and SMS, keep one primary integration without conditions so WorldVisa has something to fall back to.

If the integration still has conditions from the older dashboard, you'll see a warning in the panel. Saving new conditions replaces the old ones.

## How WorldVisa picks the integration

WorldVisa checks conditions at the moment the step sends a message, not when you save the integration. The behavior depends on the channel.

### Email and SMS

Email and SMS send through one integration per message. WorldVisa picks it in this order:

1. If the trigger passes `integrationIdentifier` in `overrides.email` or `overrides.sms`, WorldVisa uses that integration. Conditions aren't checked at all for that step, including any conditions on the integration you passed.
2. If the trigger doesn't pass `integrationIdentifier`, WorldVisa goes through the active integrations that have conditions, starting with the highest priority. When two have the same priority, the newer one goes first. The first integration whose conditions match sends the message.
3. If no conditions match, WorldVisa uses the primary integration.

Active integrations that have no conditions and aren't primary are never picked in steps 2 and 3.

Send this JSON body to `POST /v1/events/trigger` to send email through a specific integration, no matter what conditions are set up:

```json theme={null}
{
  "name": "invoice-paid",
  "to": { "subscriberId": "user-123" },
  "overrides": { "email": { "integrationIdentifier": "sendgrid-acme" } }
}
```

If `sendgrid-acme` doesn't exist or isn't active, WorldVisa doesn't fall back to conditions or the primary integration. The step fails, and the activity feed shows that no active integration was found.

For more on passing an integration in overrides, see [Targeting a specific provider](https://docs.worldvisagroup.com/developers/integrations/email#targeting-a-specific-provider) for email and [Target a specific provider](https://docs.worldvisagroup.com/developers/integrations/sms#target-a-specific-provider) for SMS.

### Chat and push

Chat and push can send through more than one integration for the same subscriber, so there's no single integration to pick and no primary fallback.

For chat connections stored as channel endpoints, such as Slack and Teams, WorldVisa checks each integration before sending. Endpoints on integrations without conditions always receive the message. Endpoints on integrations whose conditions don't match are skipped. If every integration has conditions and none match, nothing is sent.

For push, and for older chat setups where the webhook URL or token is saved on the subscriber, WorldVisa sends through whichever integration holds those credentials. Conditions on that integration don't stop the send. If you don't want a tenant to receive push or chat through an integration, don't save their credentials on it.

Passing `integrationIdentifier` in the email or SMS overrides has no effect on chat. Chat endpoints still go through their own condition checks.

## What conditions can use

Conditions can read subscriber, context, and workflow data. They can't use payload values or results from earlier steps. If you need those, use [step conditions](https://docs.worldvisagroup.com/developers/workflow/add-and-configure-steps/step-conditions.md) instead.

Integrations that already had `payload.*` rules saved before this change will keep working, but you can't add new ones.

These fields are available in the dashboard:

| Field | Example use |
| - | - |
| `context.tenant.id` | Send through a tenant's own provider account |
| `subscriber.subscriberId` | Use an integration for one specific subscriber |
| `subscriber.email`, `subscriber.phone` | Match on contact details |
| `subscriber.firstName`, `subscriber.lastName` | Match on name |
| `subscriber.locale` | Pick a provider by language or region |
| `subscriber.data` | Match custom attributes, such as `subscriber.data.plan` |
| `workflow.workflowId` | Pick a provider for a specific workflow |
| `workflow.name` | Match on the workflow name |
| `workflow.description` | Match on the workflow description |
| `workflow.tags` | Match on workflow tags, using operators like contains any of |
| `workflow.severity` | Pick a provider by workflow severity |

You can also use other `context.*` and `subscriber.*` paths, like `context.tenant.data.plan` or `subscriber.data.region`. Payload paths and `workflow.*` fields not listed above are rejected.

To set `context.tenant.id`, pass a tenant in the JSON body sent to `POST /v1/events/trigger`:

```json theme={null}
{
  "name": "invoice-paid",
  "to": { "subscriberId": "user-123" },
  "context": { "tenant": "acme-corp" }
}
```

Passing `"acme-corp"` or `{ id: "acme-corp" }` both set `context.tenant.id` to `acme-corp`. See [Contexts](https://docs.worldvisagroup.com/developers/concepts/contexts.md) and [Multi-tenancy](https://docs.worldvisagroup.com/developers/concepts/tenants.md) for more.

## Example: a separate email provider for one tenant

You can use different providers per tenant. Say your default email provider is SendGrid, and your customer Acme wants their emails sent from their own account.

1. Keep your default SendGrid integration active and primary, with no conditions.
2. Add a second email integration using Acme's credentials. Don't make it primary.
3. Open **Integration conditions** on the Acme integration and add `context.tenant.id` equals `acme-corp`.
4. Trigger your workflow with `context: { tenant: "acme-corp" }`. Those emails go through Acme's integration, and everything else goes through your default SendGrid integration.

## Manage conditions with the API

Conditions are saved as JSON Logic in the integration's `rules` field. You can set `rules` when you create or update an integration with the Integrations API.

```json theme={null}
{
  "and": [
    { "==": [{ "var": "context.tenant.id" }, "acme-corp"] },
    { "==": [{ "var": "subscriber.locale" }, "fr"] }
  ]
}
```

The API accepts the same fields as the dashboard. Payload paths and unknown `workflow.*` fields are rejected.

Updating an integration with `rules` removes its primary flag and replaces any older conditions. Creating an integration is different. If it's the first active email or SMS integration in the environment, WorldVisa can still make it primary even if you pass `rules`. When that happens and the rules don't match, WorldVisa still sends through it as the primary fallback. To avoid this, create your primary integration first without conditions, then add the integrations that have conditions.

## Related

> [card] [Integrations](https://docs.worldvisagroup.com/developers/concepts/integrations.md)
>
> How integrations, primary, and active flags work

> [card] [Step conditions](https://docs.worldvisagroup.com/developers/workflow/add-and-configure-steps/step-conditions.md)
>
> Skip or run workflow steps based on payload and subscriber data

> [card] [Contexts](https://docs.worldvisagroup.com/developers/concepts/contexts.md)
>
> Pass tenant and other context on the trigger

> [card] [Multi-tenancy](https://docs.worldvisagroup.com/developers/concepts/tenants.md)
>
> Isolate Inbox, preferences, and providers per tenant


## Related topics

- [Integrations](https://docs.worldvisagroup.com/developers/concepts/integrations.md)
- [Multi-tenancy](https://docs.worldvisagroup.com/developers/concepts/tenants.md)
- [Step Conditions](https://docs.worldvisagroup.com/developers/workflow/add-and-configure-steps/step-conditions.md)
- [E-mail](https://docs.worldvisagroup.com/developers/integrations/email.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.