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

# Communications

> The channels your organisation has, their fallback order, prices, stock and usage, managed by your administrators.

When the internet path to a zone is not available, wede delivers through the channels assigned to your organisation (SMS, voice, satellite, LoRa or others), in the order you set. These endpoints let your administrators read what the organisation has and set that order without wede. The same view is the Communications page of the dashboard.

You only ever see what is assigned to your organisation: each provider by its name, whether it is bought from wede or is your own API connected to wede, the price you pay (for channels bought from wede), the stock allocated for the year, this year's usage and the usage above what your plan includes. Adding or removing a provider is done with wede.

## Authentication

Session token (`Authorization: Bearer <token>`) of a `company_admin` or `company_tech`. Any other role, wede staff included, receives `403 forbidden`. API keys are not accepted.

## Read communications

```http theme={null}
GET /v1/tenant/communications
```

```bash theme={null}
curl https://api.wede.pt/v1/tenant/communications \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"
```

```json Response 200 theme={null}
{
  "year": 2026,
  "country": "PT",
  "currency": "EUR",
  "estimate_total": 12.5,
  "channels": [
    {
      "channel": "sms",
      "enabled": true,
      "timeout_seconds": 30,
      "billed_by": "wede",
      "price": { "per_unit": 0.05, "unit": "per message", "currency": "EUR" },
      "included": 0,
      "usage": { "units": 250, "segments": 300 },
      "stock": { "allocated": 1000, "used": 250, "remaining": 750, "source": "plan" },
      "estimate": { "overage_units": 250, "amount": 12.5, "currency": "EUR" },
      "providers": [
        { "integration_id": "e7a1a31e-ca75-4bad-be85-d870088c1493", "name": "SMS Portugal", "ownership": "wede", "verified": true, "in_cascade": true, "priority": 1, "timeout_seconds": 30, "is_active": true, "price": { "per_unit": 0.05, "unit": "per message", "currency": "EUR" } }
      ]
    },
    {
      "channel": "voice",
      "enabled": true,
      "timeout_seconds": 45,
      "billed_by": "own_provider",
      "price": null,
      "included": 0,
      "usage": { "units": 12 },
      "stock": null,
      "estimate": null,
      "providers": [
        { "integration_id": "2b9e3055-1529-4bf8-892e-167fb30ff061", "name": "Our voice gateway", "ownership": "own_api", "verified": true, "in_cascade": true, "priority": 1, "timeout_seconds": 45, "is_active": true }
      ]
    }
  ]
}
```

**channels** `object[]`

One entry per channel assigned to your organisation, in fallback order (channels not yet in the order come last).

**channels\[].enabled** `boolean`

`true` when the channel has at least one active provider in the order. A channel turned off is skipped.

**channels\[].timeout\_seconds** `integer`

Seconds wede waits for a delivery on this channel before trying the next.

**channels\[].providers** `object[]`

The providers assigned to your organisation for this channel: `name`, `ownership` (`wede`, bought from wede; `own_api`, your own provider connected to wede), `verified` (a real delivery already went through), `in_cascade` (part of the order), `priority` (position in the order), `timeout_seconds`, `is_active`, and `price` for providers bought from wede.

**channels\[].billed\_by** `string`

`wede` when the channel is bought from wede; `own_provider` when every provider of the channel is your own API, billed by your provider.

**channels\[].price** `object | null`

The price you pay per unit for channels bought from wede, as in Billing. `null` for channels billed by your own provider.

**channels\[].stock** `object | null`

The stock allocated to your organisation for the year (`allocated`, `used`, `remaining`, `source`: `plan` or `manual`). `null` when nothing is allocated.

**channels\[].usage** `object`

Events delivered through this channel this year (`units`) and, for SMS, the `segments` sent to field teams.

**channels\[].included** `integer`

Units included in your plan for the year.

**channels\[].estimate** `object | null`

Usage above what your plan includes (`overage_units`) and its `amount` at your price. `null` for channels billed by your own provider. `estimate_total` sums every channel. Usage above the plan is counted and shown here; it is not billed yet.

## Set the fallback order

```http theme={null}
PUT /v1/tenant/communications/cascade
```

Replaces the order. Channels come in the order wede should try them; inside each channel, `providers` are integration ids in the order wede should try them. A channel with no providers leaves the order.

**channels** `object[]` *required*

Up to 20 items, each with `channel`, `providers` (up to 10 integration ids assigned to your organisation for that channel), optional `enabled` (default `true`) and optional `timeout_seconds` (1 to 600, default 30).

```bash theme={null}
curl -X PUT https://api.wede.pt/v1/tenant/communications/cascade \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channels": [
      { "channel": "voice", "providers": ["2b9e3055-1529-4bf8-892e-167fb30ff061"], "timeout_seconds": 20 },
      { "channel": "sms", "providers": ["e7a1a31e-ca75-4bad-be85-d870088c1493"], "enabled": false }
    ]
  }'
```

Returns `200` with the same body as the read. New events follow the new order from then on. The change is written to the audit log.

## Errors

| Status | `error` | When |
| - | - | - |
| `400` | `validation_error` | `channels` is malformed, a channel is repeated, or a timeout is outside 1 to 600. |
| `401` | `unauthorized` | Missing, invalid or expired credentials. |
| `403` | `forbidden` | Your role is not `company_admin` or `company_tech`, or you used an API key. |
| `422` | `provider_not_assigned` | An integration in `providers` is not assigned to your organisation for that channel. Nothing is changed. |


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