{
  "openapi": "3.1.0",
  "info": {
    "title": "WhatsApp Gateway API",
    "description": "Send and receive WhatsApp messages through numbers paired by QR code.\n\n**Authentication.** Operations take an API key (`wag_live_…`), as `Authorization: Bearer <key>` or\n`X-Api-Key: <key>`. Each operation names the scope its key needs in its security requirement.\n\n**Errors** answer `{ \"error\": \"…\" }` with the HTTP status; match on the status, not the text.\nSomeone else's resource answers 404, exactly like a missing one.\n\n**Limits.** Requests are rate limited per client IP (429 with Retry-After); sends are queued and paced\nper number (POST /connections/{id}/send answers 202 with the job).\n\n**Webhooks.** Events are POSTed to the tenant's webhookBaseUrl (see the webhooks section), signed with\nX-Sales-Signature when the tenant has a webhookSecret. Delivery is at least once.",
    "version": "1.0.0"
  },
  "components": {
    "schemas": {
      "WebhookEventEnvelope": {
        "type": "object",
        "description": "Body of every webhook POST. Consumers must ignore event types they do not know.\n\nHeaders: X-Webhook-Token always. When the tenant has a webhookSecret, also\nX-Sales-Timestamp (unix seconds, taken per delivery attempt) and\nX-Sales-Signature = \"sha256=\" + hex(HMAC-SHA256(webhookSecret, timestamp + \".\" + rawBody)).\nVerify over the raw body bytes and reject a timestamp more than 300 s from your clock.\n\nDelivery is at-least-once (retries, reconnect replays): apply events idempotently, keyed on data.messageId.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "connection.status",
              "message.incoming",
              "message.outgoing",
              "message.delivery",
              "message.send_failed",
              "message.reaction",
              "contact.resolved",
              "group.joined",
              "group.left",
              "group.updated"
            ]
          },
          "connectionId": {
            "type": "string",
            "format": "uuid"
          },
          "tenantId": {
            "type": "string",
            "format": "uuid"
          },
          "externalId": {
            "type": [
              "string",
              "null"
            ]
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "type",
          "connectionId",
          "tenantId",
          "externalId",
          "timestamp",
          "data"
        ]
      },
      "ConnectionStatusEvent": {
        "type": "object",
        "description": "data of connection.status: the socket opened or closed, or WhatsApp changed what the account may do. A close the gateway reports carries why (reason) and whether the gateway reconnects on its own (willReconnect). willReconnect true (transient, restart_required) means the gateway keeps retrying with backoff until it opens again, reported by the next status open; false means it stopped and waits for a human: a new QR (logged_out, qr_not_scanned) or an explicit reconnect (replaced, manual). passkey_required: the QR was scanned but pairing never completed because WhatsApp asked the phone for a passkey; status is close, there is no phoneNumber (the link never confirmed one), and no more QR codes are generated until the connection is connected again. reachout_timelock: WhatsApp put the account under a reach-out timelock (sent after a 463 or a WhatsApp notification; status is the current one, normally open); until reachoutTimelock.endsAt (or a reachout_timelock_lifted event) every queued send is dropped as message.send_failed reason reachout_timelocked instead of being attempted. reason is absent on an open; willReconnect and statusCode are present only on a close with one of the first six reasons.",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "connecting",
              "open",
              "close"
            ]
          },
          "phoneNumber": {
            "type": "string",
            "description": "Digits of the paired number, when known; absent with passkey_required."
          },
          "reason": {
            "type": "string",
            "enum": [
              "transient",
              "restart_required",
              "replaced",
              "qr_not_scanned",
              "logged_out",
              "manual",
              "reachout_timelock",
              "reachout_timelock_lifted",
              "passkey_required"
            ],
            "description": "Why the event was sent. On a close: transient, restart_required, replaced, qr_not_scanned, logged_out, manual or passkey_required. The reachout_timelock* reasons come with the current status."
          },
          "willReconnect": {
            "type": "boolean",
            "description": "Only on a close with reason transient, restart_required, replaced, qr_not_scanned, logged_out or manual: whether the gateway reconnects on its own."
          },
          "statusCode": {
            "type": [
              "number",
              "null"
            ],
            "description": "Only with willReconnect. WhatsApp disconnect code (e.g. 401 logged out, 440 replaced, 503 stream error), null when there was none; for diagnostics: branch on reason, not on this."
          },
          "reachoutTimelock": {
            "type": "object",
            "description": "Present with the reachout_timelock* reasons.",
            "properties": {
              "active": {
                "type": "boolean"
              },
              "endsAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "null when WhatsApp gave no end."
              },
              "enforcementType": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "WhatsApp's enforcement type, e.g. DEFAULT or BIZ_QUALITY."
              }
            },
            "required": [
              "active",
              "endsAt",
              "enforcementType"
            ]
          }
        },
        "required": [
          "status"
        ]
      },
      "MessageOutgoingEvent": {
        "type": "object",
        "description": "data of message.outgoing: a message the paired number sent in a 1:1 chat. Emitted once per messageId, and only to a tenant created or patched with emitOutgoing: true (off by default). origin API = the gateway sent it through POST /connections/:id/send (the id was recorded before sending, so this is a lookup, never a guess); origin PHONE = typed on the phone or another linked device. Groups, status broadcasts and newsletters are not reported.",
        "properties": {
          "messageId": {
            "type": "string"
          },
          "origin": {
            "type": "string",
            "enum": [
              "API",
              "PHONE"
            ]
          },
          "clientRef": {
            "type": [
              "string",
              "null"
            ],
            "description": "Echo of the send's clientRef for origin API; always null for PHONE."
          },
          "to": {
            "type": "string",
            "description": "Raw WhatsApp JID of the other party (…@s.whatsapp.net or …@lid). Always present."
          },
          "jid": {
            "type": "string",
            "description": "Raw WhatsApp JID of the other party (…@s.whatsapp.net or …@lid). Always present."
          },
          "toE164": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\+[1-9]\\d{7,14}$",
            "description": "Same value as phone."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\+[1-9]\\d{7,14}$",
            "description": "E.164 phone of the other party (e.g. \"+5511999999999\"). null when the chat is addressed by a LID the gateway could not resolve (or for group chats). The event is never dropped for that reason."
          },
          "body": {
            "type": "string",
            "description": "Text, or the media caption; empty for media without caption."
          },
          "timestamp": {
            "type": "number",
            "description": "Unix seconds."
          },
          "mediaType": {
            "type": "string",
            "enum": [
              "image",
              "video",
              "audio",
              "document",
              "sticker",
              "location"
            ]
          }
        },
        "required": [
          "messageId",
          "origin",
          "clientRef",
          "to",
          "jid",
          "toE164",
          "phone",
          "body",
          "timestamp"
        ]
      },
      "MessageIncomingEvent": {
        "type": "object",
        "description": "data of message.incoming: a message someone sent to the number, in a 1:1 chat or a group it is in (then jid is the group and phone is null).",
        "properties": {
          "from": {
            "type": "string",
            "description": "Raw sender JID (kept for existing consumers)."
          },
          "jid": {
            "type": "string",
            "description": "Raw WhatsApp JID of the other party (…@s.whatsapp.net or …@lid). Always present."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\+[1-9]\\d{7,14}$",
            "description": "E.164 phone of the other party (e.g. \"+5511999999999\"). null when the chat is addressed by a LID the gateway could not resolve (or for group chats). The event is never dropped for that reason."
          },
          "resolvedPhone": {
            "type": "string",
            "description": "Digits only, legacy field; absent when unresolved."
          },
          "to": {
            "type": "string",
            "description": "JID of the paired number, with its linked-device suffix."
          },
          "body": {
            "type": "string",
            "description": "Text, caption or button/list reply; empty for media without caption and locations."
          },
          "timestamp": {
            "type": "number",
            "description": "Unix seconds."
          },
          "media": {
            "type": "object",
            "description": "Present when the message carries media the gateway downloaded.",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "image",
                  "video",
                  "audio",
                  "document",
                  "sticker"
                ]
              },
              "url": {
                "type": "string",
                "format": "uri",
                "description": "Signed, expiring link to the file: <MEDIA_BASE_URL>/media/<connectionId>/<fileName>?exp=<unix seconds>&sig=<base64url>. GET it without credentials, exactly as received, until expiresAt; unsigned, expired or altered it answers 404. It is a bearer credential for this file until then: download the file instead of storing or forwarding the link."
              },
              "mimetype": {
                "type": "string"
              },
              "fileName": {
                "type": "string"
              },
              "fileSize": {
                "type": "number",
                "description": "Bytes."
              },
              "expiresAt": {
                "type": "number",
                "description": "Unix ms when url stops working: its own expiry or the file cleanup, whichever comes first."
              }
            },
            "required": [
              "type",
              "url",
              "mimetype",
              "fileName",
              "fileSize",
              "expiresAt"
            ]
          },
          "location": {
            "type": "object",
            "description": "Present for a location or live-location message.",
            "properties": {
              "latitude": {
                "type": "number"
              },
              "longitude": {
                "type": "number"
              },
              "name": {
                "type": "string"
              },
              "address": {
                "type": "string"
              }
            },
            "required": [
              "latitude",
              "longitude"
            ]
          },
          "raw": {
            "type": "object",
            "additionalProperties": true,
            "description": "The message as WhatsApp Web delivered it (the WebMessageInfo of the pinned Baileys version). Its shape follows WhatsApp, not this contract: prefer the fields above and read raw only for what they do not carry."
          }
        },
        "required": [
          "from",
          "jid",
          "phone",
          "body",
          "timestamp"
        ]
      },
      "MessageDeliveryEvent": {
        "type": "object",
        "description": "data of message.delivery: a status change of a message the number sent.",
        "properties": {
          "messageId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "sent",
              "delivered",
              "read",
              "failed"
            ]
          },
          "recipient": {
            "type": "string",
            "description": "Legacy: JID with @s.whatsapp.net stripped (a LID passes through as-is)."
          },
          "jid": {
            "type": "string",
            "description": "Raw WhatsApp JID of the other party (…@s.whatsapp.net or …@lid). Always present."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\+[1-9]\\d{7,14}$",
            "description": "E.164 phone of the other party (e.g. \"+5511999999999\"). null when the chat is addressed by a LID the gateway could not resolve (or for group chats). The event is never dropped for that reason."
          },
          "clientRef": {
            "type": [
              "string",
              "null"
            ],
            "description": "The clientRef passed to POST /connections/:id/send for this message; null when none was given or the message was not sent through the API."
          },
          "reason": {
            "type": "string",
            "enum": [
              "reachout_timelocked"
            ],
            "description": "Only with status failed, when WhatsApp said why; absent otherwise. reachout_timelocked: WhatsApp refused the message as a reach-out (ack error 463, typically a contact the number never talked to); it was not delivered and is not retried. Resending makes the restriction worse; see connection.status reason reachout_timelock."
          }
        },
        "required": [
          "messageId",
          "status",
          "recipient",
          "jid",
          "phone",
          "clientRef"
        ]
      },
      "MessageSendFailedEvent": {
        "type": "object",
        "description": "data of message.send_failed: a job queued by POST /connections/:id/send WITH a clientRef that the gateway gave up on (attempts exhausted, its lease expired on the last attempt, the number is not on WhatsApp, or the account is under a WhatsApp reach-out timelock and the send was refused without being attempted). Never emitted for a job without a clientRef. A retry with the same clientRef keeps answering duplicate, so this is the consumer's only signal that the accepted send will not happen; a deliberate resend uses a new clientRef. If an echo or a delivery status for the same clientRef arrives later, that proof wins.",
        "properties": {
          "clientRef": {
            "type": "string"
          },
          "jobId": {
            "type": "string"
          },
          "messageId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null."
          },
          "to": {
            "type": "string",
            "description": "The /send `to` as queued."
          },
          "jid": {
            "type": "string",
            "description": "Raw WhatsApp JID of the other party (…@s.whatsapp.net or …@lid). Always present."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\+[1-9]\\d{7,14}$",
            "description": "E.164 phone of the other party (e.g. \"+5511999999999\"). null when the chat is addressed by a LID the gateway could not resolve (or for group chats). The event is never dropped for that reason."
          },
          "reason": {
            "type": "string",
            "enum": [
              "attempts_exhausted",
              "lease_expired",
              "not_on_whatsapp",
              "reachout_timelocked"
            ]
          },
          "attempts": {
            "type": "number"
          }
        },
        "required": [
          "clientRef",
          "jobId",
          "messageId",
          "to",
          "jid",
          "phone",
          "reason",
          "attempts"
        ]
      },
      "ContactResolvedEvent": {
        "type": "object",
        "description": "data of contact.resolved. A sender that earlier reached this tenant as a LID with phone: null now has a known phone number. Emitted once per pending LID per connection, only to the tenant that received those messages. Re-attribute every earlier event whose jid equals data.lid.",
        "properties": {
          "lid": {
            "type": "string",
            "description": "The LID JID the earlier events carried, e.g. 123456789012345@lid."
          },
          "jid": {
            "type": "string",
            "description": "Raw WhatsApp JID of the other party (…@s.whatsapp.net or …@lid). Always present."
          },
          "phone": {
            "type": "string",
            "pattern": "^\\+[1-9]\\d{7,14}$",
            "description": "E.164 phone of the other party (e.g. \"+5511999999999\"). null when the chat is addressed by a LID the gateway could not resolve (or for group chats). The event is never dropped for that reason."
          },
          "firstSeenAt": {
            "type": "string",
            "format": "date-time",
            "description": "First message from this LID with no phone."
          },
          "messageCount": {
            "type": "number",
            "description": "Messages received from this LID while it had no phone."
          },
          "source": {
            "type": "string",
            "enum": [
              "lid-mapping",
              "contacts",
              "sweep"
            ]
          }
        },
        "required": [
          "lid",
          "jid",
          "phone",
          "firstSeenAt",
          "messageCount",
          "source"
        ]
      },
      "MessageReactionEvent": {
        "type": "object",
        "description": "data of message.reaction.",
        "properties": {
          "messageId": {
            "type": "string"
          },
          "from": {
            "type": "string",
            "description": "Legacy: JID with @s.whatsapp.net stripped."
          },
          "jid": {
            "type": "string",
            "description": "Raw WhatsApp JID of the other party (…@s.whatsapp.net or …@lid). Always present."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\+[1-9]\\d{7,14}$",
            "description": "E.164 phone of the other party (e.g. \"+5511999999999\"). null when the chat is addressed by a LID the gateway could not resolve (or for group chats). The event is never dropped for that reason."
          },
          "emoji": {
            "type": "string",
            "description": "Empty string = reaction removed."
          }
        },
        "required": [
          "messageId",
          "from",
          "jid",
          "phone",
          "emoji"
        ]
      },
      "GroupJoinedEvent": {
        "type": "object",
        "description": "data of group.joined: the number joined or was added to a group. Also sent once per group the number is already in when its connection first opens in this gateway process (not again on reconnects).",
        "properties": {
          "groupId": {
            "type": "string",
            "description": "Group JID (…@g.us)."
          },
          "groupName": {
            "type": "string",
            "description": "The group subject; absent when unknown."
          },
          "participantCount": {
            "type": "number",
            "description": "Absent when unknown."
          }
        },
        "required": [
          "groupId"
        ]
      },
      "GroupLeftEvent": {
        "type": "object",
        "description": "data of group.left: the number was removed from a group.",
        "properties": {
          "groupId": {
            "type": "string",
            "description": "Group JID (…@g.us)."
          },
          "reason": {
            "type": "string",
            "enum": [
              "kicked"
            ]
          }
        },
        "required": [
          "groupId",
          "reason"
        ]
      },
      "GroupUpdatedEvent": {
        "type": "object",
        "description": "data of group.updated: a group the number is in changed.",
        "properties": {
          "groupId": {
            "type": "string",
            "description": "Group JID (…@g.us)."
          },
          "groupName": {
            "type": "string",
            "description": "The new subject; absent when the update did not change it."
          }
        },
        "required": [
          "groupId"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Every error body. Match on the HTTP status: `error` is a message for people and may change.",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string",
            "description": "Details, on validation errors and rate limits."
          },
          "statusCode": {
            "type": "integer"
          },
          "code": {
            "type": "string",
            "description": "On validation errors: FST_ERR_VALIDATION. On plan limits: subscription_inactive (402), number_limit_reached (402), plan_feature_required (403)."
          },
          "feature": {
            "type": "string",
            "description": "plan_feature_required: the feature the organization's plan lacks."
          },
          "missingVariables": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "A send with a template: the variables it lacks."
          }
        },
        "required": [
          "error"
        ]
      }
    },
    "parameters": {
      "WebhookToken": {
        "name": "X-Webhook-Token",
        "in": "header",
        "required": true,
        "description": "The tenant's webhookToken (write-only on POST and PATCH /tenants). The tenant's custom webhookHeaders are sent too.",
        "schema": {
          "type": "string"
        }
      },
      "WebhookTimestamp": {
        "name": "X-Sales-Timestamp",
        "in": "header",
        "required": false,
        "description": "Only when the tenant has a webhookSecret: unix seconds of this delivery attempt (retries are signed again). Reject one more than 300 s from your clock.",
        "schema": {
          "type": "string",
          "pattern": "^\\d+$"
        },
        "example": "1790251200"
      },
      "WebhookSignature": {
        "name": "X-Sales-Signature",
        "in": "header",
        "required": false,
        "description": "Only when the tenant has a webhookSecret: \"sha256=\" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + \".\" + rawBody)). Compute it over the raw body bytes as received, never a re-serialized object, and compare in constant time.",
        "schema": {
          "type": "string",
          "pattern": "^sha256=[0-9a-f]{64}$"
        },
        "example": "sha256=6d1f0c4e9b2a7f3e8c5d1a0b9e8f7a6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request does not match the operation's schema.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "statusCode": 400,
              "code": "FST_ERR_VALIDATION",
              "error": "Bad Request",
              "message": "body must have required property 'to'"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "No API key, or not a valid one (unknown, revoked or expired).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "Unauthorized"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The API key lacks the scope in this operation's security requirement, or the organization's plan lacks the feature the operation needs (`code: plan_feature_required`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "This credential lacks the messages:send scope"
            }
          }
        }
      },
      "PaymentRequired": {
        "description": "The organization cannot use WhatsApp now: its trial ended, or an invoice is overdue past the grace period (`code: subscription_inactive`). Creating a number past the ones contracted: `code: number_limit_reached`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "The organization cannot use WhatsApp now: its trial ended or an invoice is overdue. Pay to resume",
              "code": "subscription_inactive"
            }
          }
        }
      },
      "NotFound": {
        "description": "Not among the caller's resources: someone else's answers exactly like a missing one.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "Not found"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too many requests from this client IP, or too many failed authentications: wait Retry-After seconds.",
        "headers": {
          "Retry-After": {
            "description": "Seconds until the client may try again.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "statusCode": 429,
              "error": "Too Many Requests",
              "message": "Rate limit exceeded, retry in 1 minute"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The gateway instance that runs the connection is changing (a restart, a failover) or does not answer: wait Retry-After seconds and try again.",
        "headers": {
          "Retry-After": {
            "description": "Seconds until the client may try again.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "The connection cannot be reached right now: the gateway instance that runs it is changing or does not answer; try again in a few seconds"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "wag_live_<prefix>_<secret>",
        "description": "API key as `Authorization: Bearer wag_live_…`."
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "name": "X-Api-Key",
        "in": "header",
        "description": "API key as `X-Api-Key: wag_live_…`."
      }
    }
  },
  "paths": {
    "/me": {
      "get": {
        "operationId": "getCaller",
        "summary": "Who is calling",
        "tags": [
          "Account"
        ],
        "description": "The credential this request authenticated with: its kind, its organization, the scopes it holds and the tenants it is pinned to. An API key reaches only `tenantIds`; a dashboard user (`kind: user`, signed in with the dashboard's session cookie) reaches every tenant of the organization and of its child organizations, with the scopes of the user's role.",
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The calling credential.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The calling credential.",
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "apiKey",
                        "user",
                        "platform"
                      ],
                      "description": "`platform`: the operator"
                    },
                    "user": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "The signed-in user; null for an API key",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "email": {
                          "type": "string",
                          "format": "email"
                        },
                        "name": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "email",
                        "name"
                      ]
                    },
                    "organization": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "The organization the credential acts for: the key's tenant's, or the user's current one",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "slug": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "name",
                        "slug"
                      ]
                    },
                    "role": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "enum": [
                        "owner",
                        "admin",
                        "member",
                        null
                      ],
                      "description": "A user's role in the organization"
                    },
                    "scopes": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "connections:read",
                          "connections:write",
                          "messages:send",
                          "templates:write",
                          "webhooks:write",
                          "logs:read",
                          "usage:read",
                          "keys:read",
                          "keys:write",
                          "billing:write",
                          "projects:write"
                        ]
                      }
                    },
                    "tenantIds": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "description": "The tenants an API key is pinned to; null: every tenant of the organization's"
                    },
                    "apiKey": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "expiresAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "expiresAt"
                      ]
                    }
                  },
                  "required": [
                    "kind",
                    "user",
                    "organization",
                    "role",
                    "scopes",
                    "tenantIds",
                    "apiKey"
                  ]
                },
                "examples": {
                  "example1": {
                    "value": {
                      "kind": "apiKey",
                      "user": null,
                      "organization": {
                        "id": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
                        "name": "Acme",
                        "slug": "acme"
                      },
                      "role": null,
                      "scopes": [
                        "connections:read",
                        "messages:send"
                      ],
                      "tenantIds": [
                        "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61"
                      ],
                      "apiKey": {
                        "id": "5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
                        "expiresAt": null
                      }
                    }
                  },
                  "example2": {
                    "value": {
                      "kind": "user",
                      "user": {
                        "id": "b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e",
                        "email": "ana@acme.example",
                        "name": "Ana"
                      },
                      "organization": {
                        "id": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
                        "name": "Acme",
                        "slug": "acme"
                      },
                      "role": "member",
                      "scopes": [
                        "connections:read",
                        "connections:write",
                        "messages:send",
                        "templates:write",
                        "webhooks:write",
                        "logs:read",
                        "usage:read",
                        "keys:read"
                      ],
                      "tenantIds": null,
                      "apiKey": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/tenants": {
      "get": {
        "operationId": "listTenants",
        "summary": "List tenants",
        "tags": [
          "Tenants"
        ],
        "description": "Returns the caller's tenants (every tenant for the platform) with their organization's plan and connection count.",
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The caller's tenants, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The caller's tenants, newest first.",
                  "type": "object",
                  "properties": {
                    "tenants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "organizationId": {
                            "type": "string",
                            "format": "uuid",
                            "description": "The organization (customer account) that owns the tenant"
                          },
                          "name": {
                            "type": "string"
                          },
                          "webhookBaseUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "webhookHeaderNames": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Names of the custom headers sent with every delivery; their values are write-only"
                          },
                          "emitOutgoing": {
                            "type": "boolean"
                          },
                          "maxPerMinute": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "maxPerHour": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "maxPerDay": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "hasWebhookSecret": {
                            "type": "boolean"
                          },
                          "planId": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The organization's plan"
                          },
                          "subscriptionStatus": {
                            "type": "string",
                            "description": "The organization's subscription"
                          },
                          "trialEndsAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "currentPeriodEnd": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "isActive": {
                            "type": "boolean"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "plan": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "displayName": {
                                "type": "string"
                              },
                              "maxConnections": {
                                "type": "number",
                                "description": "-1 = unlimited"
                              },
                              "maxMessagesDay": {
                                "type": "number",
                                "description": "-1 = unlimited"
                              },
                              "maxMessagesMonth": {
                                "type": "number",
                                "description": "-1 = unlimited"
                              },
                              "monthlyPriceCents": {
                                "type": "number",
                                "description": "-1 = custom"
                              }
                            }
                          },
                          "connectionCount": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "count": {
                      "type": "number"
                    }
                  }
                },
                "example": {
                  "tenants": [
                    {
                      "id": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                      "organizationId": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
                      "name": "acme-crm",
                      "webhookBaseUrl": "https://crm.example.com/api/whatsapp/events",
                      "webhookHeaderNames": [
                        "X-Crm-Account"
                      ],
                      "emitOutgoing": true,
                      "maxPerMinute": null,
                      "maxPerHour": null,
                      "maxPerDay": null,
                      "hasWebhookSecret": true,
                      "planId": "b7e2c9d4-1f3a-4c5b-8d6e-9f0a1b2c3d4e",
                      "subscriptionStatus": "active",
                      "trialEndsAt": null,
                      "currentPeriodEnd": "2026-10-24T12:00:00.000Z",
                      "isActive": true,
                      "createdAt": "2026-09-01T12:00:00.000Z",
                      "updatedAt": "2026-09-24T12:00:00.000Z",
                      "plan": {
                        "id": "b7e2c9d4-1f3a-4c5b-8d6e-9f0a1b2c3d4e",
                        "name": "pro",
                        "displayName": "Pro",
                        "maxConnections": 5,
                        "maxMessagesDay": 1000,
                        "maxMessagesMonth": 20000,
                        "monthlyPriceCents": 9900
                      },
                      "connectionCount": 1
                    }
                  ],
                  "count": 1
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/tenants/webhook-test": {
      "post": {
        "operationId": "testWebhook",
        "summary": "Test a webhook endpoint",
        "tags": [
          "Tenants"
        ],
        "description": "Sends a signed `ping` event to the given endpoint with the same headers, signing, 10s timeout and URL rules as real deliveries (redirects are not followed; a host that resolves to a non-public address is refused when it connects). Nothing is saved. With tenantId, that tenant must be yours.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "webhookBaseUrl": {
                    "type": "string",
                    "description": "URL to POST the ping to; same rules as a tenant webhookBaseUrl"
                  },
                  "webhookToken": {
                    "type": "string",
                    "description": "Omitted: the tenant's stored token, only when webhookBaseUrl is the tenant's saved URL"
                  },
                  "webhookHeaders": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "Omitted: the tenant's stored headers, only when webhookBaseUrl is the tenant's saved URL"
                  },
                  "webhookSecret": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "tenantId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Sign with this tenant's stored secret when webhookSecret is omitted"
                  }
                },
                "required": [
                  "webhookBaseUrl"
                ]
              },
              "example": {
                "webhookBaseUrl": "https://crm.example.com/hooks/whatsapp",
                "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61"
              }
            }
          }
        },
        "security": [
          {
            "apiKeyBearer": [
              "webhooks:write"
            ]
          },
          {
            "apiKeyHeader": [
              "webhooks:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "What the endpoint answered to the ping; nothing is saved.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "What the endpoint answered to the ping; nothing is saved.",
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "status": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "HTTP status; null when no response came back"
                    },
                    "latencyMs": {
                      "type": "number"
                    },
                    "error": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "\"timeout\" when the 10s limit fired"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "status": 200,
                  "latencyMs": 184,
                  "error": null
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/tenants/{id}": {
      "get": {
        "operationId": "getTenant",
        "summary": "Get tenant by ID",
        "tags": [
          "Tenants"
        ],
        "description": "Returns tenant details including connection count.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The tenant.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The tenant.",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "organizationId": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The organization (customer account) that owns the tenant"
                    },
                    "name": {
                      "type": "string"
                    },
                    "webhookBaseUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "webhookHeaderNames": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Names of the custom headers sent with every delivery; their values are write-only"
                    },
                    "emitOutgoing": {
                      "type": "boolean"
                    },
                    "maxPerMinute": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "maxPerHour": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "maxPerDay": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "hasWebhookSecret": {
                      "type": "boolean"
                    },
                    "planId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The organization's plan"
                    },
                    "subscriptionStatus": {
                      "type": "string",
                      "description": "The organization's subscription"
                    },
                    "trialEndsAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "currentPeriodEnd": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "isActive": {
                      "type": "boolean"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "connectionCount": {
                      "type": "number"
                    }
                  }
                },
                "example": {
                  "id": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                  "organizationId": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
                  "name": "acme-crm",
                  "webhookBaseUrl": "https://crm.example.com/api/whatsapp/events",
                  "webhookHeaderNames": [
                    "X-Crm-Account"
                  ],
                  "emitOutgoing": true,
                  "maxPerMinute": null,
                  "maxPerHour": null,
                  "maxPerDay": null,
                  "hasWebhookSecret": true,
                  "planId": "b7e2c9d4-1f3a-4c5b-8d6e-9f0a1b2c3d4e",
                  "subscriptionStatus": "active",
                  "trialEndsAt": null,
                  "currentPeriodEnd": "2026-10-24T12:00:00.000Z",
                  "isActive": true,
                  "createdAt": "2026-09-01T12:00:00.000Z",
                  "updatedAt": "2026-09-24T12:00:00.000Z",
                  "connectionCount": 1
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "patch": {
        "operationId": "updateTenant",
        "summary": "Update tenant",
        "tags": [
          "Tenants"
        ],
        "description": "Updates tenant webhook configuration or rate limits. 409 also answers a same-origin browser request that changes webhookToken or webhookHeaders without X-Admin-Client: an outdated admin dashboard that would overwrite them. name, webhookBaseUrl, planId, isActive and the maxPer* overrides are for the platform only (403 for an organization credential).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "webhookBaseUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Same rules as on create; checked only when it changes."
                  },
                  "webhookToken": {
                    "type": "string",
                    "description": "Write-only: never returned."
                  },
                  "webhookHeaders": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "Replaces the custom headers; null removes them. Write-only: only their names are returned."
                  },
                  "webhookSecret": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Signing secret for deliveries; null or \"\" turns signing off. Write-only: never returned."
                  },
                  "emitOutgoing": {
                    "type": "boolean",
                    "description": "Opt-in to message.outgoing events."
                  },
                  "maxPerMinute": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "maxPerHour": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "maxPerDay": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "isActive": {
                    "type": "boolean"
                  },
                  "planId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Plan to assign to the tenant's organization (billing is per organization: every tenant of it moves); null removes it. Must exist."
                  }
                }
              },
              "example": {
                "emitOutgoing": true
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "webhooks:write"
            ]
          },
          {
            "apiKeyHeader": [
              "webhooks:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The updated tenant.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "organizationId": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The organization (customer account) that owns the tenant"
                    },
                    "name": {
                      "type": "string"
                    },
                    "webhookBaseUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "webhookHeaderNames": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Names of the custom headers sent with every delivery; their values are write-only"
                    },
                    "emitOutgoing": {
                      "type": "boolean"
                    },
                    "maxPerMinute": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "maxPerHour": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "maxPerDay": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "hasWebhookSecret": {
                      "type": "boolean"
                    },
                    "planId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The organization's plan"
                    },
                    "subscriptionStatus": {
                      "type": "string",
                      "description": "The organization's subscription"
                    },
                    "trialEndsAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "currentPeriodEnd": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "isActive": {
                      "type": "boolean"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "description": "The updated tenant."
                },
                "example": {
                  "id": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                  "organizationId": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
                  "name": "acme-crm",
                  "webhookBaseUrl": "https://crm.example.com/api/whatsapp/events",
                  "webhookHeaderNames": [
                    "X-Crm-Account"
                  ],
                  "emitOutgoing": true,
                  "maxPerMinute": null,
                  "maxPerHour": null,
                  "maxPerDay": null,
                  "hasWebhookSecret": true,
                  "planId": "b7e2c9d4-1f3a-4c5b-8d6e-9f0a1b2c3d4e",
                  "subscriptionStatus": "active",
                  "trialEndsAt": null,
                  "currentPeriodEnd": "2026-10-24T12:00:00.000Z",
                  "isActive": true,
                  "createdAt": "2026-09-01T12:00:00.000Z",
                  "updatedAt": "2026-09-24T12:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "delete": {
        "operationId": "deleteTenant",
        "summary": "Delete tenant",
        "tags": [
          "Tenants"
        ],
        "description": "Deactivates a tenant and all its connections: they are disconnected, their sessions kept.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:write"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Deleted.",
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "deleted": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/tenants/{id}/connections": {
      "get": {
        "operationId": "listTenantConnections",
        "summary": "List tenant connections",
        "tags": [
          "Tenants"
        ],
        "description": "Returns all connections for a specific tenant, with their stored status.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The tenant's connections, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The tenant's connections, newest first.",
                  "type": "object",
                  "properties": {
                    "connections": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "tenantId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "tenantName": {
                            "type": "string"
                          },
                          "externalId": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "PENDING",
                              "CONNECTING",
                              "OPEN",
                              "CLOSE",
                              "FAILED",
                              "PASSKEY_REQUIRED"
                            ]
                          },
                          "phoneNumber": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "lastHeartbeat": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "lastConnectedAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "count": {
                      "type": "number"
                    }
                  }
                },
                "example": {
                  "connections": [
                    {
                      "id": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                      "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                      "tenantName": "acme-crm",
                      "externalId": "shop-42",
                      "status": "OPEN",
                      "phoneNumber": "5511900000001",
                      "lastHeartbeat": "2026-09-24T12:00:00.000Z",
                      "lastConnectedAt": "2026-09-24T08:00:00.000Z",
                      "createdAt": "2026-09-01T12:00:00.000Z"
                    }
                  ],
                  "count": 1
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "post": {
        "operationId": "createTenantConnection",
        "summary": "Create a connection in a tenant",
        "tags": [
          "Tenants"
        ],
        "description": "Like POST /connections, for the tenant in the path: creates a WhatsApp connection (or connects the one its externalId names) and answers it as GET /tenants/{id}/connections lists it. Each connection takes one of the numbers the tenant's organization contracted until it is deleted: past them, 402 `number_limit_reached`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "externalId": {
                    "type": "string",
                    "description": "Optional tenant-specific identifier (e.g., businessId)"
                  },
                  "proxy": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "required": [
                      "url"
                    ],
                    "additionalProperties": false,
                    "properties": {
                      "url": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 2048,
                        "description": "socks5://, socks5h:// (the proxy resolves hostnames in both), http:// or https:// (HTTP CONNECT), with optional user:password@. Write-only."
                      },
                      "country": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "pattern": "^[A-Za-z]{2}$",
                        "description": "The country the proxy must exit from (ISO 3166-1 alpha-2, e.g. BR); omitted or null: any"
                      }
                    },
                    "description": "The connection's own proxy, as PUT /connections/{id}/proxy takes it",
                    "example": {
                      "url": "socks5://user:password@br.proxy.example.com:1080",
                      "country": "BR"
                    }
                  }
                }
              },
              "example": {
                "externalId": "shop-42"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:write"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The connection, pending until it is paired.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The connection, pending until it is paired.",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "tenantId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "externalId": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "status": {
                      "type": "string"
                    },
                    "phoneNumber": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "lastHeartbeat": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "lastConnectedAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                },
                "example": {
                  "id": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                  "externalId": "shop-42",
                  "status": "pending",
                  "phoneNumber": null,
                  "lastHeartbeat": null,
                  "lastConnectedAt": null,
                  "createdAt": "2026-09-24T12:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "The check through the proxy failed: nothing was created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The check through the proxy failed: nothing was created."
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Connection created but not persisted"
                }
              }
            }
          },
          "501": {
            "description": "The connection's provider cannot do this: `unsupported_by_provider`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The connection's provider cannot do this: `unsupported_by_provider`."
                },
                "example": {
                  "error": "unsupported_by_provider"
                }
              }
            }
          },
          "503": {
            "description": "This gateway cannot store proxy URLs: no encryption key is configured.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "This gateway cannot store proxy URLs: no encryption key is configured."
                }
              }
            }
          }
        }
      }
    },
    "/tenants/{id}/connections/{connId}": {
      "get": {
        "operationId": "getTenantConnection",
        "summary": "Get connection details",
        "tags": [
          "Tenants"
        ],
        "description": "Returns connection details including its 50 most recent events (heartbeat successes excepted).",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "connId",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The connection and its recent events, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The connection and its recent events, newest first.",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "tenantId": {
                      "type": "string"
                    },
                    "externalId": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "status": {
                      "type": "string"
                    },
                    "phoneNumber": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "lastHeartbeat": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "lastConnectedAt": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "createdAt": {
                      "type": "string"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "eventType": {
                            "type": "string"
                          },
                          "details": {
                            "type": [
                              "object",
                              "null"
                            ]
                          },
                          "createdAt": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "id": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                  "externalId": "shop-42",
                  "status": "open",
                  "phoneNumber": "5511900000001",
                  "lastHeartbeat": "2026-09-24T12:00:00.000Z",
                  "lastConnectedAt": "2026-09-24T08:00:00.000Z",
                  "createdAt": "2026-09-01T12:00:00.000Z",
                  "events": [
                    {
                      "id": "e4f5a6b7-c8d9-4e0f-8a1b-2c3d4e5f6a7b",
                      "eventType": "CONNECTED",
                      "details": {
                        "phoneNumber": "5511900000001"
                      },
                      "createdAt": "2026-09-24T08:00:00.000Z"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "delete": {
        "operationId": "deleteTenantConnection",
        "summary": "Delete a connection",
        "tags": [
          "Tenants"
        ],
        "description": "Logs the number out (the linked device leaves the phone) and deletes the connection with its session, templates and history. Cannot be undone. When the number cannot be logged out, nothing is deleted: 409, try again.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "connId",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:write"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Done.",
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/tenants/{id}/connections/{connId}/heartbeats": {
      "get": {
        "operationId": "getConnectionHeartbeats",
        "summary": "Connection heartbeat history",
        "tags": [
          "Tenants"
        ],
        "description": "Half-hour buckets, oldest first (the last one is the current, partial one). ok=false when a heartbeat failed in the bucket, true when one succeeded, null without data.",
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 168,
              "default": 24
            },
            "in": "query",
            "name": "hours",
            "required": false
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "connId",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The uptime history.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The uptime history.",
                  "type": "object",
                  "properties": {
                    "buckets": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "start": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "ok": {
                            "type": [
                              "boolean",
                              "null"
                            ]
                          }
                        }
                      }
                    },
                    "uptimePct": {
                      "type": [
                        "number",
                        "null"
                      ]
                    }
                  }
                },
                "example": {
                  "buckets": [
                    {
                      "start": "2026-09-24T11:00:00.000Z",
                      "ok": true
                    },
                    {
                      "start": "2026-09-24T11:30:00.000Z",
                      "ok": false
                    },
                    {
                      "start": "2026-09-24T12:00:00.000Z",
                      "ok": null
                    }
                  ],
                  "uptimePct": 50
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/tenants/{id}/connections/{connId}/qr": {
      "get": {
        "operationId": "getTenantConnectionQr",
        "summary": "Get the QR code as an image",
        "tags": [
          "Tenants"
        ],
        "description": "Like GET /connections/{id}/qr, with the QR code rendered as a PNG data URL, ready to use as an image source, and likewise only for a caller holding connections:write (null otherwise). status is the live one, else the stored one (lowercase).",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "connId",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The QR code image while pairing, and the status.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The QR code image while pairing, and the status.",
                  "type": "object",
                  "properties": {
                    "qrCode": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "PNG data URL; null when there is no QR code to scan, or the caller lacks connections:write"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
                  "status": "connecting"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/tenants/{id}/connections/{connId}/disconnect": {
      "post": {
        "operationId": "disconnectTenantConnection",
        "summary": "Disconnect a connection",
        "tags": [
          "Tenants"
        ],
        "description": "Like POST /connections/{id}/disconnect: closes the socket and keeps the session.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "connId",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:write"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Done.",
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/tenants/{id}/connections/{connId}/connect": {
      "post": {
        "operationId": "reconnectTenantConnection",
        "summary": "Connect a connection again",
        "tags": [
          "Tenants"
        ],
        "description": "Starts the socket of a closed connection: with its session, it reconnects; without one, pairing starts and GET /connections/{id}/qr shows the QR code.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "connId",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:write"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Done.",
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/tenants/{id}/api-keys": {
      "get": {
        "operationId": "listApiKeys",
        "summary": "List a tenant's API keys",
        "tags": [
          "API keys"
        ],
        "description": "The tenant's keys, newest first: every key that still works and the 100 most recent revoked or expired ones. Never the keys themselves.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "keys:read"
            ]
          },
          {
            "apiKeyHeader": [
              "keys:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The tenant's keys, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The tenant's keys, newest first.",
                  "type": "object",
                  "properties": {
                    "apiKeys": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "tenantId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "organizationId": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The tenant's organization"
                          },
                          "name": {
                            "type": "string"
                          },
                          "prefix": {
                            "type": "string",
                            "description": "Identifies the key; not secret"
                          },
                          "maskedKey": {
                            "type": "string",
                            "description": "wag_live_<prefix>_…, to recognise the key"
                          },
                          "scopes": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "connections:read",
                                "connections:write",
                                "messages:send",
                                "templates:write",
                                "webhooks:write",
                                "logs:read",
                                "usage:read",
                                "keys:read",
                                "keys:write"
                              ]
                            }
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "active",
                              "expired",
                              "revoked"
                            ]
                          },
                          "createdBy": {
                            "type": "string",
                            "description": "\"apiKey:<id>\" of the key that created it, \"user:<id>\" of the dashboard user, or \"platform\""
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "lastUsedAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time",
                            "description": "Updated at most once a minute"
                          },
                          "expiresAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "revokedAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "rotatedAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time",
                            "description": "When a rotation replaced the key: it works until expiresAt at the latest and cannot be rotated again"
                          }
                        }
                      }
                    },
                    "count": {
                      "type": "number"
                    }
                  }
                },
                "example": {
                  "apiKeys": [
                    {
                      "id": "5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
                      "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                      "organizationId": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
                      "name": "CRM production",
                      "prefix": "k3x9p2ab",
                      "maskedKey": "wag_live_k3x9p2ab_…",
                      "scopes": [
                        "connections:read",
                        "messages:send"
                      ],
                      "status": "active",
                      "createdBy": "platform",
                      "createdAt": "2026-09-01T12:00:00.000Z",
                      "lastUsedAt": "2026-09-24T12:00:00.000Z",
                      "expiresAt": null,
                      "revokedAt": null,
                      "rotatedAt": null
                    }
                  ],
                  "count": 1
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "post": {
        "operationId": "createApiKey",
        "summary": "Create an API key",
        "tags": [
          "API keys"
        ],
        "description": "Creates a key for the tenant, sent as `Authorization: Bearer <key>` or `X-Api-Key: <key>`. The answer carries the key once; store it now. An API key can only grant scopes it holds itself, and an expiring API key only keys that expire no later than it does. An inactive tenant gets no new keys (409).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100,
                    "description": "What the key is for"
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "connections:read",
                        "connections:write",
                        "messages:send",
                        "templates:write",
                        "webhooks:write",
                        "logs:read",
                        "usage:read",
                        "keys:read",
                        "keys:write"
                      ]
                    },
                    "minItems": 1,
                    "uniqueItems": true
                  },
                  "expiresAt": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time",
                    "description": "When the key stops working; null or absent: never"
                  }
                },
                "required": [
                  "name",
                  "scopes"
                ],
                "additionalProperties": false
              },
              "example": {
                "name": "CRM production",
                "scopes": [
                  "connections:read",
                  "messages:send"
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "keys:write"
            ]
          },
          {
            "apiKeyHeader": [
              "keys:write"
            ]
          }
        ],
        "responses": {
          "201": {
            "description": "The key, with the key itself shown this once.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "tenantId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "organizationId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The tenant's organization"
                    },
                    "name": {
                      "type": "string"
                    },
                    "prefix": {
                      "type": "string",
                      "description": "Identifies the key; not secret"
                    },
                    "maskedKey": {
                      "type": "string",
                      "description": "wag_live_<prefix>_…, to recognise the key"
                    },
                    "scopes": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "connections:read",
                          "connections:write",
                          "messages:send",
                          "templates:write",
                          "webhooks:write",
                          "logs:read",
                          "usage:read",
                          "keys:read",
                          "keys:write"
                        ]
                      }
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "active",
                        "expired",
                        "revoked"
                      ]
                    },
                    "createdBy": {
                      "type": "string",
                      "description": "\"apiKey:<id>\" of the key that created it, \"user:<id>\" of the dashboard user, or \"platform\""
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "lastUsedAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time",
                      "description": "Updated at most once a minute"
                    },
                    "expiresAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "revokedAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "rotatedAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time",
                      "description": "When a rotation replaced the key: it works until expiresAt at the latest and cannot be rotated again"
                    },
                    "key": {
                      "type": "string",
                      "description": "The key itself, shown this once: only its SHA-256 is stored, so it cannot be shown again"
                    }
                  },
                  "description": "The key, with the key itself shown this once."
                },
                "example": {
                  "id": "6f9a2b3c-4d5e-4f6a-9b0c-1d2e3f4a5b6c",
                  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                  "organizationId": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
                  "name": "CRM production",
                  "prefix": "q7m4w1zc",
                  "maskedKey": "wag_live_q7m4w1zc_…",
                  "scopes": [
                    "connections:read",
                    "messages:send"
                  ],
                  "status": "active",
                  "createdBy": "platform",
                  "createdAt": "2026-09-24T12:00:00.000Z",
                  "lastUsedAt": null,
                  "expiresAt": null,
                  "revokedAt": null,
                  "rotatedAt": null,
                  "key": "wag_live_q7m4w1zc_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/tenants/{id}/api-keys/{keyId}": {
      "delete": {
        "operationId": "revokeApiKey",
        "summary": "Revoke an API key",
        "tags": [
          "API keys"
        ],
        "description": "The key stops working at once. The row stays listed (status revoked) for the audit trail.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "keyId",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "keys:write"
            ]
          },
          {
            "apiKeyHeader": [
              "keys:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The revoked key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "tenantId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "organizationId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The tenant's organization"
                    },
                    "name": {
                      "type": "string"
                    },
                    "prefix": {
                      "type": "string",
                      "description": "Identifies the key; not secret"
                    },
                    "maskedKey": {
                      "type": "string",
                      "description": "wag_live_<prefix>_…, to recognise the key"
                    },
                    "scopes": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "connections:read",
                          "connections:write",
                          "messages:send",
                          "templates:write",
                          "webhooks:write",
                          "logs:read",
                          "usage:read",
                          "keys:read",
                          "keys:write"
                        ]
                      }
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "active",
                        "expired",
                        "revoked"
                      ]
                    },
                    "createdBy": {
                      "type": "string",
                      "description": "\"apiKey:<id>\" of the key that created it, \"user:<id>\" of the dashboard user, or \"platform\""
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "lastUsedAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time",
                      "description": "Updated at most once a minute"
                    },
                    "expiresAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "revokedAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "rotatedAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time",
                      "description": "When a rotation replaced the key: it works until expiresAt at the latest and cannot be rotated again"
                    }
                  },
                  "description": "The revoked key."
                },
                "example": {
                  "id": "5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
                  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                  "organizationId": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
                  "name": "CRM production",
                  "prefix": "k3x9p2ab",
                  "maskedKey": "wag_live_k3x9p2ab_…",
                  "scopes": [
                    "connections:read",
                    "messages:send"
                  ],
                  "status": "revoked",
                  "createdBy": "platform",
                  "createdAt": "2026-09-01T12:00:00.000Z",
                  "lastUsedAt": "2026-09-24T12:00:00.000Z",
                  "expiresAt": null,
                  "revokedAt": "2026-09-24T12:00:00.000Z",
                  "rotatedAt": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/tenants/{id}/api-keys/{keyId}/rotate": {
      "post": {
        "operationId": "rotateApiKey",
        "summary": "Rotate an API key",
        "tags": [
          "API keys"
        ],
        "description": "Creates a new key with the old one's name, scopes and expiry, shown once. The old key keeps working for overlapSeconds (default 24 hours), so callers can switch without downtime; 0 revokes it at once. A key is rotated once: rotating it again, or a revoked or expired key, is 409.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "overlapSeconds": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 604800
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "overlapSeconds": 3600
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "keyId",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "keys:write"
            ]
          },
          {
            "apiKeyHeader": [
              "keys:write"
            ]
          }
        ],
        "responses": {
          "201": {
            "description": "The new key (shown this once) and the old one, retired after the overlap.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The new key (shown this once) and the old one, retired after the overlap.",
                  "type": "object",
                  "properties": {
                    "apiKey": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "tenantId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "organizationId": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The tenant's organization"
                        },
                        "name": {
                          "type": "string"
                        },
                        "prefix": {
                          "type": "string",
                          "description": "Identifies the key; not secret"
                        },
                        "maskedKey": {
                          "type": "string",
                          "description": "wag_live_<prefix>_…, to recognise the key"
                        },
                        "scopes": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "connections:read",
                              "connections:write",
                              "messages:send",
                              "templates:write",
                              "webhooks:write",
                              "logs:read",
                              "usage:read",
                              "keys:read",
                              "keys:write"
                            ]
                          }
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "active",
                            "expired",
                            "revoked"
                          ]
                        },
                        "createdBy": {
                          "type": "string",
                          "description": "\"apiKey:<id>\" of the key that created it, \"user:<id>\" of the dashboard user, or \"platform\""
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "lastUsedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time",
                          "description": "Updated at most once a minute"
                        },
                        "expiresAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "revokedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "rotatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time",
                          "description": "When a rotation replaced the key: it works until expiresAt at the latest and cannot be rotated again"
                        },
                        "key": {
                          "type": "string",
                          "description": "The key itself, shown this once: only its SHA-256 is stored, so it cannot be shown again"
                        }
                      }
                    },
                    "previous": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "tenantId": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "organizationId": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The tenant's organization"
                        },
                        "name": {
                          "type": "string"
                        },
                        "prefix": {
                          "type": "string",
                          "description": "Identifies the key; not secret"
                        },
                        "maskedKey": {
                          "type": "string",
                          "description": "wag_live_<prefix>_…, to recognise the key"
                        },
                        "scopes": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "connections:read",
                              "connections:write",
                              "messages:send",
                              "templates:write",
                              "webhooks:write",
                              "logs:read",
                              "usage:read",
                              "keys:read",
                              "keys:write"
                            ]
                          }
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "active",
                            "expired",
                            "revoked"
                          ]
                        },
                        "createdBy": {
                          "type": "string",
                          "description": "\"apiKey:<id>\" of the key that created it, \"user:<id>\" of the dashboard user, or \"platform\""
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "lastUsedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time",
                          "description": "Updated at most once a minute"
                        },
                        "expiresAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "revokedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "rotatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time",
                          "description": "When a rotation replaced the key: it works until expiresAt at the latest and cannot be rotated again"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "apiKey": {
                    "id": "6f9a2b3c-4d5e-4f6a-9b0c-1d2e3f4a5b6c",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "organizationId": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
                    "name": "CRM production",
                    "prefix": "q7m4w1zc",
                    "maskedKey": "wag_live_q7m4w1zc_…",
                    "scopes": [
                      "connections:read",
                      "messages:send"
                    ],
                    "status": "active",
                    "createdBy": "platform",
                    "createdAt": "2026-09-24T12:00:00.000Z",
                    "lastUsedAt": null,
                    "expiresAt": null,
                    "revokedAt": null,
                    "rotatedAt": null,
                    "key": "wag_live_q7m4w1zc_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8"
                  },
                  "previous": {
                    "id": "5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "organizationId": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
                    "name": "CRM production",
                    "prefix": "k3x9p2ab",
                    "maskedKey": "wag_live_k3x9p2ab_…",
                    "scopes": [
                      "connections:read",
                      "messages:send"
                    ],
                    "status": "active",
                    "createdBy": "platform",
                    "createdAt": "2026-09-01T12:00:00.000Z",
                    "lastUsedAt": "2026-09-24T12:00:00.000Z",
                    "expiresAt": "2026-09-24T13:00:00.000Z",
                    "revokedAt": null,
                    "rotatedAt": "2026-09-24T12:00:00.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/connections": {
      "get": {
        "operationId": "listConnections",
        "summary": "List connections",
        "tags": [
          "Connections"
        ],
        "description": "Returns the connections of the caller's active tenants with their current status. FAILED connections are left out unless includeFailed=true.",
        "parameters": [
          {
            "schema": {
              "type": "boolean",
              "default": false
            },
            "in": "query",
            "name": "includeFailed",
            "required": false
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The connections, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The connections, newest first.",
                  "type": "object",
                  "properties": {
                    "connections": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "tenantId": {
                            "type": "string"
                          },
                          "tenantName": {
                            "type": "string"
                          },
                          "lastConnectedAt": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "externalId": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "description": "Live status when this process holds the socket (connecting, open, close, passkey_required), else the stored one (lowercase)."
                          },
                          "phoneNumber": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "lastHeartbeat": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "createdAt": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "count": {
                      "type": "number"
                    }
                  }
                },
                "example": {
                  "connections": [
                    {
                      "id": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                      "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                      "tenantName": "acme-crm",
                      "externalId": "shop-42",
                      "status": "open",
                      "phoneNumber": "5511900000001",
                      "lastHeartbeat": "2026-09-24T12:00:00.000Z",
                      "lastConnectedAt": "2026-09-24T08:00:00.000Z",
                      "createdAt": "2026-09-01T12:00:00.000Z"
                    }
                  ],
                  "count": 1
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "post": {
        "operationId": "createConnection",
        "summary": "Create a new WhatsApp connection",
        "tags": [
          "Connections"
        ],
        "description": "Creates a new WhatsApp connection for a tenant (or connects the one its externalId names). Returns a connectionId to use for QR code scanning. Each connection takes one of the numbers the tenant's organization contracted until it is deleted: past them, 402 `number_limit_reached` (connecting the one an externalId names takes none). With proxy, its proxy is checked first (400, 422 or 503 when refused, and nothing is created) and stored before its first socket: not even its first QR code leaves around it.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tenantId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Tenant ID"
                  },
                  "externalId": {
                    "type": "string",
                    "description": "Optional tenant-specific identifier (e.g., businessId)"
                  },
                  "proxy": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "required": [
                      "url"
                    ],
                    "additionalProperties": false,
                    "properties": {
                      "url": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 2048,
                        "description": "socks5://, socks5h:// (the proxy resolves hostnames in both), http:// or https:// (HTTP CONNECT), with optional user:password@. Write-only."
                      },
                      "country": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "pattern": "^[A-Za-z]{2}$",
                        "description": "The country the proxy must exit from (ISO 3166-1 alpha-2, e.g. BR); omitted or null: any"
                      }
                    },
                    "description": "The connection's own proxy, as PUT /connections/{id}/proxy takes it: its socket, media uploads and downloads leave through it from the first one",
                    "example": {
                      "url": "socks5://user:password@br.proxy.example.com:1080",
                      "country": "BR"
                    }
                  }
                },
                "required": [
                  "tenantId"
                ]
              },
              "example": {
                "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                "externalId": "shop-42"
              }
            }
          }
        },
        "security": [
          {
            "apiKeyBearer": [
              "connections:write"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The connection: pair it with GET /connections/{id}/qr or POST /connections/{id}/pairing-code.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The connection: pair it with GET /connections/{id}/qr or POST /connections/{id}/pairing-code.",
                  "type": "object",
                  "properties": {
                    "connectionId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "externalId": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                },
                "example": {
                  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                  "externalId": "shop-42"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "The check through the proxy failed: nothing was created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The check through the proxy failed: nothing was created."
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "501": {
            "description": "The connection's provider cannot do this: `unsupported_by_provider`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The connection's provider cannot do this: `unsupported_by_provider`."
                },
                "example": {
                  "error": "unsupported_by_provider"
                }
              }
            }
          },
          "503": {
            "description": "This gateway cannot store proxy URLs: no encryption key is configured.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "This gateway cannot store proxy URLs: no encryption key is configured."
                }
              }
            }
          }
        }
      }
    },
    "/connections/{id}/qr": {
      "get": {
        "operationId": "getConnectionQr",
        "summary": "Get QR code and connection status",
        "tags": [
          "Connections"
        ],
        "description": "Returns the current QR code (if available) and connection status. The QR code is shown only to a caller holding connections:write: scanning it links a number to the connection, as POST /connections/{id}/pairing-code does. With connections:read alone, qr is null and status is still returned. status passkey_required: the QR was scanned but the pairing never completed, because WhatsApp asked the phone for a passkey, which this gateway cannot complete yet. The socket is stopped (no more QR codes) until the connection is connected again, also across restarts (the status is stored); the number can be paired later or another number used.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true,
            "description": "Connection ID"
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The QR code to scan, while the connection is pairing, and the status.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The QR code to scan, while the connection is pairing, and the status.",
                  "type": "object",
                  "properties": {
                    "qr": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "QR code string for scanning; null when there is none, or the caller lacks connections:write"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "connecting",
                        "open",
                        "close",
                        "passkey_required"
                      ]
                    }
                  }
                },
                "example": {
                  "qr": "2@k8Jd0Qf3mX1pT7vZ9sLr4eYw6nHc2bGa,5oVt8yRk3uEi1wQz7xNm4cPl0dFg6hJs=,Zx9Cv8Bn7Ma6Sd5Fg4Hj3Kl2",
                  "status": "connecting"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/connections/{id}/pairing-code": {
      "post": {
        "operationId": "requestPairingCode",
        "summary": "Get a pairing code to link a number without the QR code",
        "tags": [
          "Connections"
        ],
        "description": "Asks WhatsApp for an 8-character code that links `phone` to the connection when it is typed on that phone (WhatsApp › Linked devices › Link a device › Link with phone number instead), instead of scanning the QR code. Only while the connection is pairing with its QR code up (GET /connections/{id}/qr shows one): create the connection, or connect it again, first. The phone is notified. The code is valid until `expiresAt`, when the QR codes of this pairing end (at most about 2.5 minutes after they came up) and the connection shows new ones: ask for a new code then. When they end too soon for a code to be typed, 409 `not_pairing` with Retry-After says when the next ones are up. Each code notifies the phone, so a connection may ask for one every 30 seconds and a phone may be sent 5 an hour whoever asks (429 `pairing_code_too_soon` with Retry-After). The link then completes like a scanned QR code (status open, connection.status open). **A pairing code does not avoid passkeys**: when WhatsApp asks the phone for a passkey after the code is entered, the pairing stalls exactly as after a QR scan and the connection stops as passkey_required.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "phone": {
                    "type": "string",
                    "minLength": 8,
                    "maxLength": 32,
                    "description": "The number to link, in international format: country code first (digits; +, spaces, dashes and parentheses are ignored)"
                  }
                },
                "required": [
                  "phone"
                ]
              },
              "example": {
                "phone": "5511900000001"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:write"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The code to type on the phone, the number it links (E.164) and until when it can be typed.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The code to type on the phone, the number it links (E.164) and until when it can be typed.",
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "The pairing code, 8 characters; WhatsApp shows it as two groups of 4 (K7QX-2M9P)"
                    },
                    "phone": {
                      "type": "string",
                      "description": "The number it links, E.164"
                    },
                    "expiresAt": {
                      "type": "number",
                      "description": "Unix ms the code stops working: the QR codes of this pairing end, and the connection shows new ones"
                    }
                  }
                },
                "example": {
                  "code": "K7QX2M9P",
                  "phone": "+5511900000001",
                  "expiresAt": 1790251365000
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "No pairing a code could join: `already_paired` (the connection is linked to a number, or a link is completing: log it out to link another) or `not_pairing` (it is not pairing with a QR code up: connect it again, or retry in a few seconds while it starts; with Retry-After when its QR codes end too soon for a code to be typed).",
            "content": {
              "application/json": {
                "schema": {
                  "description": "No pairing a code could join: `already_paired` (the connection is linked to a number, or a link is completing: log it out to link another) or `not_pairing` (it is not pairing with a QR code up: connect it again, or retry in a few seconds while it starts; with Retry-After when its QR codes end too soon for a code to be typed).",
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "not_pairing",
                  "message": "The connection is not pairing with its QR code up (status: close): connect it again, then ask for a code"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to request a pairing code"
                }
              }
            }
          },
          "501": {
            "description": "The connection's provider cannot do this: `unsupported_by_provider`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The connection's provider cannot do this: `unsupported_by_provider`."
                },
                "example": {
                  "error": "unsupported_by_provider"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/connections/{id}/send": {
      "post": {
        "operationId": "sendMessage",
        "summary": "Queue a message for sending",
        "tags": [
          "Messages"
        ],
        "description": "Queues a message (text, media, location, or template) for sending with rate limiting: the answer is the queued job, and the message.outgoing / message.delivery webhooks report what happened to it. Send a clientRef to make the request idempotent and to correlate those events. 429 when the plan quota of the tenant's organization is used up (its tenants' messages sent and queued count together; X-Usage-Percent), and 429 `new_recipient_cap_reached` (with Retry-After) when the recipient exchanged no message with the number in the last 28 days since its current link (a re-pair, even of the same number, makes every contact new) and the number already reached its cap of new recipients for the last 24 hours (lower while it is linked less than 14 days; GET /connections/{id}/queue shows the cap and its use): a cold contact reached too often gets the number restricted by WhatsApp. 400 `invalid_recipient` when `to` is neither a phone number nor the JID of a person, a group, a broadcast list or a newsletter.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "to": {
                    "type": "string",
                    "description": "Recipient: a phone number, country code first (e.g., 5511999999999; its digits are read), or a JID (a person @s.whatsapp.net or @lid, a group @g.us)"
                  },
                  "message": {
                    "type": "string",
                    "description": "Text message content"
                  },
                  "typingDelay": {
                    "type": "number",
                    "description": "Typing indicator duration in ms (default: 1500)"
                  },
                  "media": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "image",
                          "video",
                          "audio",
                          "document",
                          "sticker"
                        ]
                      },
                      "url": {
                        "type": "string",
                        "format": "uri",
                        "pattern": "^https://",
                        "description": "Public https URL; private and internal addresses are refused"
                      },
                      "caption": {
                        "type": "string"
                      },
                      "fileName": {
                        "type": "string"
                      },
                      "mimetype": {
                        "type": "string"
                      },
                      "ptt": {
                        "type": "boolean",
                        "description": "Push-to-talk (voice note) for audio"
                      },
                      "gifPlayback": {
                        "type": "boolean",
                        "description": "Play video as GIF"
                      }
                    },
                    "required": [
                      "type",
                      "url"
                    ]
                  },
                  "location": {
                    "type": "object",
                    "properties": {
                      "latitude": {
                        "type": "number"
                      },
                      "longitude": {
                        "type": "number"
                      },
                      "name": {
                        "type": "string"
                      },
                      "address": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "latitude",
                      "longitude"
                    ]
                  },
                  "template": {
                    "type": "string",
                    "description": "Template name to use"
                  },
                  "variables": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "Template variable values"
                  },
                  "clientRef": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "Optional consumer id for this send. Echoed as clientRef on the message.outgoing (origin API) and message.delivery events of the message, so the consumer can correlate them without knowing the WhatsApp message id in advance. Also the idempotency key: a repeat with the same clientRef on the same connection is answered 200 with the original job and queues nothing."
                  }
                },
                "required": [
                  "to"
                ]
              },
              "examples": {
                "example1": {
                  "value": {
                    "to": "5511988887777",
                    "message": "Your appointment is confirmed for tomorrow at 10:00",
                    "clientRef": "crm-msg-1"
                  }
                },
                "example2": {
                  "value": {
                    "to": "5511988887777",
                    "media": {
                      "type": "image",
                      "url": "https://cdn.example.com/promo-october.jpg",
                      "caption": "October promo"
                    },
                    "clientRef": "crm-msg-2"
                  }
                },
                "example3": {
                  "value": {
                    "to": "5511988887777",
                    "template": "appointment_confirmation",
                    "variables": {
                      "name": "Maria",
                      "time": "10:00"
                    },
                    "clientRef": "crm-msg-3"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "messages:send"
            ]
          },
          {
            "apiKeyHeader": [
              "messages:send"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "A previous request with the same clientRef already queued this message; its job is returned and nothing is queued again.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "A previous request with the same clientRef already queued this message; its job is returned and nothing is queued again.",
                  "type": "object",
                  "properties": {
                    "jobId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "scheduledAt": {
                      "type": [
                        "null",
                        "number"
                      ]
                    },
                    "position": {
                      "type": [
                        "null",
                        "number"
                      ]
                    },
                    "duplicate": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
                  "scheduledAt": 1790251205000,
                  "position": 1,
                  "duplicate": true
                }
              }
            }
          },
          "202": {
            "description": "Queued.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Queued.",
                  "type": "object",
                  "properties": {
                    "jobId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "scheduledAt": {
                      "type": "number",
                      "description": "Unix ms when the send is due."
                    },
                    "position": {
                      "type": "number",
                      "description": "Place in the connection's queue."
                    }
                  }
                },
                "example": {
                  "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
                  "scheduledAt": 1790251205000,
                  "position": 1
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                },
                "example": {
                  "error": "invalid_recipient",
                  "message": "to must be a phone number (country code first) or the JID of a person (@s.whatsapp.net, @lid), a group (@g.us), a broadcast list or a newsletter"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/connections/{id}/queue": {
      "get": {
        "operationId": "getQueue",
        "summary": "Get queue status for a connection",
        "tags": [
          "Messages"
        ],
        "description": "Returns queue statistics and rate limit usage.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The queue and the pacing limits.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The queue and the pacing limits.",
                  "type": "object",
                  "properties": {
                    "pending": {
                      "type": "number"
                    },
                    "scheduled": {
                      "type": "number"
                    },
                    "limits": {
                      "type": "object",
                      "properties": {
                        "perMinute": {
                          "type": "number"
                        },
                        "perHour": {
                          "type": "number"
                        },
                        "perDay": {
                          "type": "number"
                        },
                        "newRecipientsPerDay": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "description": "Unique recipients who exchanged no message with the number in the last 28 days since its current link it may be sent to per rolling 24 hours; null: no cap"
                        }
                      }
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "minute": {
                          "type": "number"
                        },
                        "hour": {
                          "type": "number"
                        },
                        "day": {
                          "type": "number"
                        },
                        "newRecipients": {
                          "type": "number",
                          "description": "New recipients counted in the last 24 hours"
                        }
                      }
                    },
                    "warmup": {
                      "type": "object",
                      "description": "The warm-up of a freshly linked number: for 14 days after its link its limits are lower, and loosen step by step.",
                      "properties": {
                        "createdAt": {
                          "type": "number",
                          "description": "Unix ms the warm-up counts from: when the number was linked"
                        },
                        "messagesSent": {
                          "type": "number"
                        },
                        "isInWarmup": {
                          "type": "boolean"
                        },
                        "endsAt": {
                          "type": "number",
                          "description": "Unix ms the warm-up ends"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "pending": 1,
                  "scheduled": 2,
                  "limits": {
                    "perMinute": 3,
                    "perHour": 60,
                    "perDay": 200,
                    "newRecipientsPerDay": 100
                  },
                  "usage": {
                    "minute": 1,
                    "hour": 12,
                    "day": 40,
                    "newRecipients": 7
                  },
                  "warmup": {
                    "createdAt": 1789646400000,
                    "messagesSent": 40,
                    "isInWarmup": false,
                    "endsAt": 1790856000000
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/connections/{id}/queue/{jobId}": {
      "delete": {
        "operationId": "cancelQueuedMessage",
        "summary": "Cancel a queued message",
        "tags": [
          "Messages"
        ],
        "description": "Removes a message from the queue before it is sent.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "jobId",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "messages:send"
            ]
          },
          {
            "apiKeyHeader": [
              "messages:send"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Removed from the queue.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Removed from the queue.",
                  "type": "object",
                  "properties": {
                    "cancelled": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "cancelled": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/connections/{id}/contacts/check": {
      "post": {
        "operationId": "checkContacts",
        "summary": "Check if phone numbers are on WhatsApp",
        "tags": [
          "Contacts"
        ],
        "description": "Validates up to 100 phone numbers and returns whether they are registered on WhatsApp.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "phones": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 100,
                    "description": "Array of phone numbers to check"
                  }
                },
                "required": [
                  "phones"
                ]
              },
              "example": {
                "phones": [
                  "5511988887777",
                  "5511955550000"
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "messages:send"
            ]
          },
          {
            "apiKeyHeader": [
              "messages:send"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "One result per phone, in order.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "One result per phone, in order.",
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "phone": {
                            "type": "string"
                          },
                          "exists": {
                            "type": "boolean"
                          },
                          "jid": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "results": [
                    {
                      "phone": "5511988887777",
                      "exists": true,
                      "jid": "5511988887777@s.whatsapp.net"
                    },
                    {
                      "phone": "5511955550000",
                      "exists": false
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to check contacts"
                }
              }
            }
          },
          "501": {
            "description": "The connection's provider cannot do this: `unsupported_by_provider`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The connection's provider cannot do this: `unsupported_by_provider`."
                },
                "example": {
                  "error": "unsupported_by_provider"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/connections/{id}/profile/{phone}": {
      "get": {
        "operationId": "getContactProfile",
        "summary": "Get contact profile info",
        "tags": [
          "Contacts"
        ],
        "description": "Returns the profile status and picture URL for a contact.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "phone",
            "required": true,
            "description": "Phone number"
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "messages:send"
            ]
          },
          {
            "apiKeyHeader": [
              "messages:send"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "What WhatsApp shows of the contact; absent fields are hidden by its privacy settings.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "What WhatsApp shows of the contact; absent fields are hidden by its privacy settings.",
                  "type": "object",
                  "properties": {
                    "phone": {
                      "type": "string"
                    },
                    "name": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "status": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "pictureUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                },
                "example": {
                  "phone": "5511988887777",
                  "status": "Available",
                  "pictureUrl": "https://pps.whatsapp.net/v/t61.24694-24/profile.jpg"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to get profile"
                }
              }
            }
          },
          "501": {
            "description": "The connection's provider cannot do this: `unsupported_by_provider`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The connection's provider cannot do this: `unsupported_by_provider`."
                },
                "example": {
                  "error": "unsupported_by_provider"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/connections/{id}/react": {
      "post": {
        "operationId": "sendReaction",
        "summary": "Send a reaction to a message",
        "tags": [
          "Messages"
        ],
        "description": "Sends an emoji reaction to a specific message. Use empty string to remove reaction.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "messageId": {
                    "type": "string",
                    "description": "ID of the message to react to"
                  },
                  "to": {
                    "type": "string",
                    "description": "Recipient phone number"
                  },
                  "emoji": {
                    "type": "string",
                    "description": "Emoji to react with (empty to remove)"
                  }
                },
                "required": [
                  "messageId",
                  "to"
                ]
              },
              "example": {
                "messageId": "3EB0C767D26A1D8A3F52",
                "to": "5511988887777",
                "emoji": "👍"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "messages:send"
            ]
          },
          {
            "apiKeyHeader": [
              "messages:send"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Sent.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Sent.",
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "success": true
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to send reaction"
                }
              }
            }
          },
          "501": {
            "description": "The connection's provider cannot do this: `unsupported_by_provider`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The connection's provider cannot do this: `unsupported_by_provider`."
                },
                "example": {
                  "error": "unsupported_by_provider"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/connections/{id}/groups": {
      "get": {
        "operationId": "listGroups",
        "summary": "List groups",
        "tags": [
          "Connections"
        ],
        "description": "The groups the paired number is in, asked from WhatsApp. The connection must be open (400 otherwise), and its provider must support groups (501 otherwise).",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The groups.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The groups.",
                  "type": "object",
                  "properties": {
                    "groups": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "jid": {
                            "type": "string",
                            "description": "Group JID (…@g.us)"
                          },
                          "subject": {
                            "type": "string"
                          },
                          "size": {
                            "type": "number",
                            "description": "Participants"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "groups": [
                    {
                      "jid": "120363040000000001@g.us",
                      "subject": "Barber team",
                      "size": 3
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "501": {
            "description": "The connection's provider cannot do this: `unsupported_by_provider`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The connection's provider cannot do this: `unsupported_by_provider`."
                },
                "example": {
                  "error": "unsupported_by_provider"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/connections/{id}/disconnect": {
      "post": {
        "operationId": "disconnectConnection",
        "summary": "Disconnect a WhatsApp connection",
        "tags": [
          "Connections"
        ],
        "description": "Closes the WhatsApp connection. Session is preserved for reconnection.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:write"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Done.",
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/connections/{id}/logout": {
      "post": {
        "operationId": "logoutConnection",
        "summary": "Logout from WhatsApp",
        "tags": [
          "Connections"
        ],
        "description": "Logs out from WhatsApp and clears the session. A new QR code will be required to connect again. Use this to connect a different phone number.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:write"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Done.",
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/connections/{id}/messages/{messageId}/edit": {
      "post": {
        "operationId": "editMessage",
        "summary": "Edit a sent message",
        "tags": [
          "Messages"
        ],
        "description": "Replaces the text of a message this number sent through the API (its `messageId`, from the `/send` answer or the `message.outgoing` event) within 15 minutes of the send, as WhatsApp allows; recipients see it marked as edited. 404 for a message the API did not send from this connection (or sent more than 72 hours ago), 409 `edit_window_closed` past 15 minutes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "to": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The chat: a phone number (digits, country code first; the JID WhatsApp registered for it is used, as a send does) or a JID used as is (a group's, or the `jid` of a webhook event, which may be a LID)"
                  },
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 4096,
                    "description": "The new text"
                  }
                },
                "required": [
                  "to",
                  "text"
                ]
              },
              "example": {
                "to": "5511988887777",
                "text": "Seu horário foi confirmado para as 15h."
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "in": "path",
            "name": "messageId",
            "required": true,
            "description": "The WhatsApp id of a message this number sent through the API"
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "messages:send"
            ]
          },
          {
            "apiKeyHeader": [
              "messages:send"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Done.",
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "success": true
                }
              }
            }
          },
          "400": {
            "description": "The body is invalid, the connection is not open, or `to` is not on WhatsApp (`not_on_whatsapp`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The body is invalid, the connection is not open, or `to` is not on WhatsApp (`not_on_whatsapp`)."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to edit the message"
                }
              }
            }
          },
          "501": {
            "description": "The connection's provider cannot do this: `unsupported_by_provider`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The connection's provider cannot do this: `unsupported_by_provider`."
                },
                "example": {
                  "error": "unsupported_by_provider"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/connections/{id}/messages/{messageId}": {
      "delete": {
        "operationId": "deleteMessage",
        "summary": "Delete a sent message for everyone",
        "tags": [
          "Messages"
        ],
        "description": "Deletes for everyone a message this number sent through the API (its `messageId`): recipients see \"this message was deleted\". WhatsApp honours it for about two days after the send. 404 for a message the API did not send from this connection (or sent more than 72 hours ago).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "to": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The chat: a phone number (digits, country code first; the JID WhatsApp registered for it is used, as a send does) or a JID used as is (a group's, or the `jid` of a webhook event, which may be a LID)"
                  }
                },
                "required": [
                  "to"
                ]
              },
              "example": {
                "to": "5511988887777"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "in": "path",
            "name": "messageId",
            "required": true,
            "description": "The WhatsApp id of a message this number sent through the API"
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "messages:send"
            ]
          },
          {
            "apiKeyHeader": [
              "messages:send"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Done.",
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "success": true
                }
              }
            }
          },
          "400": {
            "description": "The body is invalid, the connection is not open, or `to` is not on WhatsApp (`not_on_whatsapp`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The body is invalid, the connection is not open, or `to` is not on WhatsApp (`not_on_whatsapp`)."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to delete the message"
                }
              }
            }
          },
          "501": {
            "description": "The connection's provider cannot do this: `unsupported_by_provider`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The connection's provider cannot do this: `unsupported_by_provider`."
                },
                "example": {
                  "error": "unsupported_by_provider"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/connections/{id}/read": {
      "post": {
        "operationId": "markMessagesRead",
        "summary": "Mark received messages as read",
        "tags": [
          "Messages"
        ],
        "description": "Sends read receipts (blue ticks) for messages received in a chat: the `messageId`s of `message.incoming` events, and as `to` the `jid` of those events. In a group, `to` is the group and `participant` the JID of the sender of the messages. Up to 100 messages per call.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "to": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The chat: a phone number (digits, country code first; the JID WhatsApp registered for it is used, as a send does) or a JID used as is (a group's, or the `jid` of a webhook event, which may be a LID)"
                  },
                  "messageIds": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "participant": {
                    "type": "string",
                    "minLength": 1,
                    "description": "In a group: the JID of whoever sent the messages"
                  }
                },
                "required": [
                  "to",
                  "messageIds"
                ]
              },
              "example": {
                "to": "5511988887777@s.whatsapp.net",
                "messageIds": [
                  "3EB0C767D26A1D8A3F52"
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "messages:send"
            ]
          },
          {
            "apiKeyHeader": [
              "messages:send"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Done.",
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "success": true
                }
              }
            }
          },
          "400": {
            "description": "The body is invalid, the connection is not open, or `to` is not on WhatsApp (`not_on_whatsapp`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The body is invalid, the connection is not open, or `to` is not on WhatsApp (`not_on_whatsapp`)."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to mark the messages read"
                }
              }
            }
          },
          "501": {
            "description": "The connection's provider cannot do this: `unsupported_by_provider`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The connection's provider cannot do this: `unsupported_by_provider`."
                },
                "example": {
                  "error": "unsupported_by_provider"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/connections/{id}/presence": {
      "post": {
        "operationId": "sendPresence",
        "summary": "Show a presence in a chat",
        "tags": [
          "Messages"
        ],
        "description": "Shows the contact \"typing…\" (`composing`) or \"recording audio…\" (`recording`) until `paused` or a message is sent; `available` shows the number online to everyone (`to` is then not used). Sends already show \"typing…\" before they leave: this is for a pause the caller controls, like an agent writing a reply.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "to": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The chat: a phone number (digits, country code first; the JID WhatsApp registered for it is used, as a send does) or a JID used as is (a group's, or the `jid` of a webhook event, which may be a LID)"
                  },
                  "state": {
                    "type": "string",
                    "enum": [
                      "composing",
                      "recording",
                      "paused",
                      "available"
                    ]
                  }
                },
                "required": [
                  "to",
                  "state"
                ]
              },
              "example": {
                "to": "5511988887777",
                "state": "composing"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "messages:send"
            ]
          },
          {
            "apiKeyHeader": [
              "messages:send"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Done.",
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "success": true
                }
              }
            }
          },
          "400": {
            "description": "The body is invalid, the connection is not open, or `to` is not on WhatsApp (`not_on_whatsapp`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The body is invalid, the connection is not open, or `to` is not on WhatsApp (`not_on_whatsapp`)."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Failed to send the presence"
                }
              }
            }
          },
          "501": {
            "description": "The connection's provider cannot do this: `unsupported_by_provider`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The connection's provider cannot do this: `unsupported_by_provider`."
                },
                "example": {
                  "error": "unsupported_by_provider"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/connections/{id}/proxy": {
      "get": {
        "operationId": "getConnectionProxy",
        "summary": "Get a connection's proxy",
        "tags": [
          "Connections"
        ],
        "description": "The proxy the connection's socket, media uploads and downloads leave through, without its credentials, and where the last check saw it exit.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The connection's proxy, or null.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The connection's proxy, or null.",
                  "type": "object",
                  "properties": {
                    "proxy": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "The connection's proxy; null when it connects directly. Its URL and credentials are write-only: never answered.",
                      "properties": {
                        "scheme": {
                          "type": "string",
                          "enum": [
                            "socks5",
                            "socks5h",
                            "http",
                            "https"
                          ]
                        },
                        "host": {
                          "type": "string"
                        },
                        "port": {
                          "type": "integer"
                        },
                        "hasCredentials": {
                          "type": "boolean",
                          "description": "Whether the URL carries a username and password"
                        },
                        "country": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The country the proxy must exit from (ISO 3166-1 alpha-2), checked before pairing; null: any"
                        },
                        "exit": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "description": "Where the last exit check through the proxy saw it exit: the IP WhatsApp sees the number at",
                          "properties": {
                            "ip": {
                              "type": "string"
                            },
                            "country": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "ISO 3166-1 alpha-2; null when the IP echo endpoint does not tell"
                            },
                            "checkedAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "example1": {
                    "value": {
                      "proxy": {
                        "scheme": "socks5",
                        "host": "br.proxy.example.com",
                        "port": 1080,
                        "hasCredentials": true,
                        "country": "BR",
                        "exit": {
                          "ip": "203.0.113.7",
                          "country": "BR",
                          "checkedAt": "2026-09-24T12:00:00.000Z"
                        }
                      }
                    }
                  },
                  "example2": {
                    "value": {
                      "proxy": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "The stored proxy cannot be opened; the gateway operator has to fix it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The stored proxy cannot be opened; the gateway operator has to fix it."
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "setConnectionProxy",
        "summary": "Set a connection's proxy",
        "tags": [
          "Connections"
        ],
        "description": "Bring your own proxy: from now on the connection's WhatsApp socket, media uploads and downloads (its own and the gateway's fetches of your media URLs) leave through it, never around it. Before it is saved, the proxy host must be public and a request through it must tell where it exits (and, with country, exit there); the same check runs again before the number pairs, and no QR code is shown from an unverified exit. On a live connection a new proxy is a planned reconnect through it; the same proxy again (a new country alone) reconnects nothing. The URL is stored encrypted and never answered. To have a new connection use a proxy from its very first socket, give it when the connection is created. Answers 503 when the gateway cannot store secrets (no encryption key configured), 422 when the check through the proxy fails (saying only how: unreachable, credentials refused, no exit address, another country), and 429 once the organization's proxy checks for the hour are used up.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "additionalProperties": false,
                "properties": {
                  "url": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 2048,
                    "description": "socks5://, socks5h:// (the proxy resolves hostnames in both), http:// or https:// (HTTP CONNECT), with optional user:password@. Write-only."
                  },
                  "country": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "pattern": "^[A-Za-z]{2}$",
                    "description": "The country the proxy must exit from (ISO 3166-1 alpha-2, e.g. BR); omitted or null: any"
                  }
                }
              },
              "example": {
                "url": "socks5://user:password@br.proxy.example.com:1080",
                "country": "BR"
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:write"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The proxy, as saved, and whether the live socket reconnected through it.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The proxy, as saved, and whether the live socket reconnected through it.",
                  "type": "object",
                  "properties": {
                    "proxy": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "The connection's proxy; null when it connects directly. Its URL and credentials are write-only: never answered.",
                      "properties": {
                        "scheme": {
                          "type": "string",
                          "enum": [
                            "socks5",
                            "socks5h",
                            "http",
                            "https"
                          ]
                        },
                        "host": {
                          "type": "string"
                        },
                        "port": {
                          "type": "integer"
                        },
                        "hasCredentials": {
                          "type": "boolean",
                          "description": "Whether the URL carries a username and password"
                        },
                        "country": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The country the proxy must exit from (ISO 3166-1 alpha-2), checked before pairing; null: any"
                        },
                        "exit": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "description": "Where the last exit check through the proxy saw it exit: the IP WhatsApp sees the number at",
                          "properties": {
                            "ip": {
                              "type": "string"
                            },
                            "country": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "ISO 3166-1 alpha-2; null when the IP echo endpoint does not tell"
                            },
                            "checkedAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        }
                      }
                    },
                    "reconnecting": {
                      "type": "boolean",
                      "description": "Whether a new socket through the new proxy is on its way (a planned reconnect of a socket that is up, or on its way up). false: the connection is stopped and uses it from its next connect, the proxy is the one it had (only the country changed), or the check before pairing refused it and the connection was stopped (its lastError says why)."
                    }
                  }
                },
                "example": {
                  "proxy": {
                    "scheme": "socks5",
                    "host": "br.proxy.example.com",
                    "port": 1080,
                    "hasCredentials": true,
                    "country": "BR",
                    "exit": {
                      "ip": "203.0.113.7",
                      "country": "BR",
                      "checkedAt": "2026-09-24T12:00:00.000Z"
                    }
                  },
                  "reconnecting": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "The check through the proxy failed: it did not answer, refused the credentials, or exits outside the country asked for.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The check through the proxy failed: it did not answer, refused the credentials, or exits outside the country asked for."
                },
                "example": {
                  "error": "Proxy check failed for socks5://br.proxy.example.com:1080: the proxy could not be reached, or did not reach the IP echo endpoint"
                }
              }
            }
          },
          "429": {
            "description": "The organization's proxy checks for this hour are used up, or the rate limit per client IP: Retry-After says in how many seconds to try again.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The organization's proxy checks for this hour are used up, or the rate limit per client IP: Retry-After says in how many seconds to try again."
                }
              }
            }
          },
          "501": {
            "description": "The connection's provider cannot do this: `unsupported_by_provider`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "The connection's provider cannot do this: `unsupported_by_provider`."
                },
                "example": {
                  "error": "unsupported_by_provider"
                }
              }
            }
          },
          "503": {
            "description": "This gateway cannot store proxy URLs: no encryption key is configured.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "This gateway cannot store proxy URLs: no encryption key is configured."
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteConnectionProxy",
        "summary": "Remove a connection's proxy",
        "tags": [
          "Connections"
        ],
        "description": "The connection connects directly from now on: a live connection reconnects without the proxy (a planned reconnect).",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:write"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Removed (or there was none).",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Removed (or there was none).",
                  "type": "object",
                  "properties": {
                    "proxy": {
                      "type": "null"
                    },
                    "reconnecting": {
                      "type": "boolean",
                      "description": "Whether a new socket through the new proxy is on its way (a planned reconnect of a socket that is up, or on its way up). false: the connection is stopped and uses it from its next connect, the proxy is the one it had (only the country changed), or the check before pairing refused it and the connection was stopped (its lastError says why)."
                    }
                  }
                },
                "example": {
                  "proxy": null,
                  "reconnecting": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/connections/{id}/dedicated-ip": {
      "get": {
        "operationId": "getConnectionDedicatedIp",
        "summary": "Get a connection's dedicated IP",
        "tags": [
          "Connections"
        ],
        "description": "Whether the number has the dedicated-IP add-on: a static Brazilian ISP IP of its own instead of one it shares with at most a few other numbers of its tenant. Bought per number by the organization's owners and admins in the dashboard (a monthly subscription); once paid, the number moves onto its dedicated IP within minutes (a planned reconnect), or as soon as one is bought for it.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The connection's live add-on, else its latest, or null.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The connection's live add-on, else its latest, or null.",
                  "type": "object",
                  "properties": {
                    "dedicatedIp": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "The connection's dedicated-IP add-on: its live one (provisioning or active), else its latest; null when it never had one.",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "connectionId": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "awaiting_payment",
                            "provisioning",
                            "active",
                            "canceled"
                          ],
                          "description": "awaiting_payment: its checkout is not paid yet; provisioning: paid, the number is not on its dedicated IP yet; active: the number goes through an IP of its own; canceled: its subscription ended (the number is back on a shared IP)"
                        },
                        "waived": {
                          "type": "boolean",
                          "description": "Granted by the gateway operator, without a subscription"
                        },
                        "lastError": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Why it is not active: waiting_for_proxy (its dedicated IP is being bought), own_proxy (the connection goes through its own proxy, which wins), connection_deleted, duplicate (a second add-on paid for a connection that has one), unplaced (ended, and no shared IP has room for the number yet)"
                        },
                        "requestedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "paidAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "activatedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "canceledAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "example1": {
                    "value": {
                      "dedicatedIp": {
                        "id": "f5a6b7c8-d9e0-4f1a-8b2c-3d4e5f6a7b8c",
                        "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                        "status": "active",
                        "waived": false,
                        "lastError": null,
                        "requestedAt": "2026-09-24T12:00:00.000Z",
                        "paidAt": "2026-09-24T12:00:00.000Z",
                        "activatedAt": "2026-09-24T12:00:00.000Z",
                        "canceledAt": null
                      }
                    }
                  },
                  "example2": {
                    "value": {
                      "dedicatedIp": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/media/{connectionId}/{fileName}": {
      "get": {
        "operationId": "getMedia",
        "summary": "Get a media file",
        "tags": [
          "Media"
        ],
        "description": "Retrieves a stored inbound media file, without a credential, through the signed URL a message.incoming webhook carries in data.media.url (valid until data.media.expiresAt). Use the URL exactly as received: unsigned, expired or altered, it answers 404, like a missing file.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "exp",
            "required": false,
            "description": "Unix seconds after which the URL answers 404."
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "sig",
            "required": false,
            "description": "base64url HMAC-SHA256 over connectionId/fileName/exp."
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "connectionId",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "fileName",
            "required": true
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "The file, with the Content-Type of its extension (image/jpeg, video/mp4, audio/ogg, application/pdf, …), cacheable until the URL expires.",
            "content": {
              "*/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "description": "Unsigned, expired, altered or missing: all answer alike.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "description": "Unsigned, expired, altered or missing: all answer alike."
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/connections/{id}/templates": {
      "post": {
        "operationId": "createTemplate",
        "summary": "Create a message template",
        "tags": [
          "Templates"
        ],
        "description": "Creates a reusable message template with variable placeholders ({{varName}}).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Template name (unique per connection)"
                  },
                  "body": {
                    "type": "string",
                    "description": "Template body with {{variables}}"
                  },
                  "media": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "image",
                          "video",
                          "audio",
                          "document",
                          "sticker"
                        ]
                      },
                      "url": {
                        "type": "string",
                        "format": "uri",
                        "pattern": "^https://",
                        "description": "Public https URL; private and internal addresses are refused"
                      },
                      "caption": {
                        "type": "string"
                      },
                      "fileName": {
                        "type": "string"
                      },
                      "mimetype": {
                        "type": "string"
                      },
                      "ptt": {
                        "type": "boolean",
                        "description": "Push-to-talk (voice note) for audio"
                      },
                      "gifPlayback": {
                        "type": "boolean",
                        "description": "Play video as GIF"
                      }
                    },
                    "required": [
                      "type",
                      "url"
                    ]
                  }
                },
                "required": [
                  "name",
                  "body"
                ]
              },
              "example": {
                "name": "appointment_confirmation",
                "body": "Hi {{name}}, see you tomorrow at {{time}}."
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "templates:write"
            ]
          },
          {
            "apiKeyHeader": [
              "templates:write"
            ]
          }
        ],
        "responses": {
          "201": {
            "description": "The template.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The template.",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "connectionId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string"
                    },
                    "body": {
                      "type": "string"
                    },
                    "media": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "image",
                            "video",
                            "audio",
                            "document",
                            "sticker"
                          ]
                        },
                        "url": {
                          "type": "string",
                          "format": "uri",
                          "pattern": "^https://",
                          "description": "Public https URL; private and internal addresses are refused"
                        },
                        "caption": {
                          "type": "string"
                        },
                        "fileName": {
                          "type": "string"
                        },
                        "mimetype": {
                          "type": "string"
                        },
                        "ptt": {
                          "type": "boolean",
                          "description": "Push-to-talk (voice note) for audio"
                        },
                        "gifPlayback": {
                          "type": "boolean",
                          "description": "Play video as GIF"
                        }
                      },
                      "required": [
                        "type",
                        "url"
                      ]
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                },
                "example": {
                  "id": "7a0b3c4d-5e6f-4a7b-8c9d-2e3f4a5b6c7d",
                  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                  "name": "appointment_confirmation",
                  "body": "Hi {{name}}, see you tomorrow at {{time}}.",
                  "createdAt": "2026-09-20T12:00:00.000Z",
                  "updatedAt": "2026-09-20T12:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "get": {
        "operationId": "listTemplates",
        "summary": "List all templates",
        "tags": [
          "Templates"
        ],
        "description": "Returns all templates for a connection.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The connection's templates.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The connection's templates.",
                  "type": "object",
                  "properties": {
                    "templates": {
                      "type": "array"
                    },
                    "count": {
                      "type": "number"
                    }
                  }
                },
                "example": {
                  "templates": [
                    {
                      "id": "7a0b3c4d-5e6f-4a7b-8c9d-2e3f4a5b6c7d",
                      "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                      "name": "appointment_confirmation",
                      "body": "Hi {{name}}, see you tomorrow at {{time}}.",
                      "createdAt": "2026-09-20T12:00:00.000Z",
                      "updatedAt": "2026-09-20T12:00:00.000Z"
                    }
                  ],
                  "count": 1
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/connections/{id}/templates/{name}": {
      "get": {
        "operationId": "getTemplate",
        "summary": "Get a template by name",
        "tags": [
          "Templates"
        ],
        "description": "Returns template details including extracted variables.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "name",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "connections:read"
            ]
          },
          {
            "apiKeyHeader": [
              "connections:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The template and the variables its body uses.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The template and the variables its body uses.",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "connectionId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string"
                    },
                    "body": {
                      "type": "string"
                    },
                    "variables": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "required": {
                            "type": "boolean"
                          }
                        }
                      }
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                },
                "example": {
                  "id": "7a0b3c4d-5e6f-4a7b-8c9d-2e3f4a5b6c7d",
                  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                  "name": "appointment_confirmation",
                  "body": "Hi {{name}}, see you tomorrow at {{time}}.",
                  "createdAt": "2026-09-20T12:00:00.000Z",
                  "updatedAt": "2026-09-20T12:00:00.000Z",
                  "variables": [
                    {
                      "name": "name",
                      "required": true
                    },
                    {
                      "name": "time",
                      "required": true
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "put": {
        "operationId": "updateTemplate",
        "summary": "Update a template",
        "tags": [
          "Templates"
        ],
        "description": "Updates template body and/or media. Set media to null to remove it.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string"
                  },
                  "media": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "image",
                          "video",
                          "audio",
                          "document",
                          "sticker"
                        ]
                      },
                      "url": {
                        "type": "string",
                        "format": "uri",
                        "pattern": "^https://",
                        "description": "Public https URL; private and internal addresses are refused"
                      },
                      "caption": {
                        "type": "string"
                      },
                      "fileName": {
                        "type": "string"
                      },
                      "mimetype": {
                        "type": "string"
                      },
                      "ptt": {
                        "type": "boolean",
                        "description": "Push-to-talk (voice note) for audio"
                      },
                      "gifPlayback": {
                        "type": "boolean",
                        "description": "Play video as GIF"
                      }
                    },
                    "required": [
                      "type",
                      "url"
                    ]
                  }
                }
              },
              "example": {
                "body": "Hi {{name}}, see you tomorrow at {{time}}. Reply YES to confirm."
              }
            }
          }
        },
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "name",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "templates:write"
            ]
          },
          {
            "apiKeyHeader": [
              "templates:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The updated template.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The updated template.",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string"
                    },
                    "body": {
                      "type": "string"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                },
                "example": {
                  "id": "7a0b3c4d-5e6f-4a7b-8c9d-2e3f4a5b6c7d",
                  "name": "appointment_confirmation",
                  "body": "Hi {{name}}, see you tomorrow at {{time}}. Reply YES to confirm.",
                  "updatedAt": "2026-09-24T12:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "delete": {
        "operationId": "deleteTemplate",
        "summary": "Delete a template",
        "tags": [
          "Templates"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "name",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "templates:write"
            ]
          },
          {
            "apiKeyHeader": [
              "templates:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Deleted.",
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "deleted": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/tenants/{id}/usage": {
      "get": {
        "operationId": "getTenantUsage",
        "summary": "Get tenant usage",
        "tags": [
          "Usage"
        ],
        "description": "Messages sent today and this month (UTC days) by the tenant, and by its organization: plans are the organization's, and every tenant of it counts against the daily and monthly limits (sends are refused with 429 once the organization's usage passes them). Also the organization's subscription, and the tenant's daily history of the last `days` days (default 30, at most 366).",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "default": "30"
            },
            "in": "query",
            "name": "days",
            "required": false
          },
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "usage:read"
            ]
          },
          {
            "apiKeyHeader": [
              "usage:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The tenant's usage, and its organization's.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "The tenant's usage, and its organization's.",
                  "type": "object",
                  "properties": {
                    "tenantId": {
                      "type": "string"
                    },
                    "plan": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "The organization's plan; null: no limits",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "displayName": {
                          "type": "string"
                        },
                        "maxMessagesDay": {
                          "type": "number"
                        },
                        "maxMessagesMonth": {
                          "type": "number"
                        }
                      }
                    },
                    "usage": {
                      "type": "object",
                      "description": "The tenant's own messages, and their share of the organization's limits",
                      "properties": {
                        "today": {
                          "type": "number"
                        },
                        "thisMonth": {
                          "type": "number"
                        },
                        "percentOfDailyLimit": {
                          "type": "number"
                        },
                        "percentOfMonthlyLimit": {
                          "type": "number"
                        }
                      }
                    },
                    "organization": {
                      "type": "object",
                      "description": "The organization's messages (every tenant of it): what the limits are enforced on",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "usage": {
                          "type": "object",
                          "properties": {
                            "today": {
                              "type": "number"
                            },
                            "thisMonth": {
                              "type": "number"
                            },
                            "percentOfDailyLimit": {
                              "type": "number"
                            },
                            "percentOfMonthlyLimit": {
                              "type": "number"
                            }
                          }
                        }
                      }
                    },
                    "subscription": {
                      "type": "object",
                      "description": "The organization's subscription",
                      "properties": {
                        "status": {
                          "type": "string"
                        },
                        "trialEndsAt": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "currentPeriodEnd": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    },
                    "dailyUsage": {
                      "type": "array",
                      "description": "The tenant's",
                      "items": {
                        "type": "object",
                        "properties": {
                          "date": {
                            "type": "string"
                          },
                          "messagesSent": {
                            "type": "number"
                          },
                          "messagesRecv": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                  "plan": {
                    "name": "pro",
                    "displayName": "Pro",
                    "maxMessagesDay": 1000,
                    "maxMessagesMonth": 20000
                  },
                  "usage": {
                    "today": 12,
                    "thisMonth": 540,
                    "percentOfDailyLimit": 1.2,
                    "percentOfMonthlyLimit": 2.7
                  },
                  "organization": {
                    "id": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
                    "usage": {
                      "today": 30,
                      "thisMonth": 1200,
                      "percentOfDailyLimit": 3,
                      "percentOfMonthlyLimit": 6
                    }
                  },
                  "subscription": {
                    "status": "active",
                    "trialEndsAt": null,
                    "currentPeriodEnd": "2026-10-24T12:00:00.000Z"
                  },
                  "dailyUsage": [
                    {
                      "date": "2026-09-23",
                      "messagesSent": 42,
                      "messagesRecv": 17
                    },
                    {
                      "date": "2026-09-24",
                      "messagesSent": 12,
                      "messagesRecv": 5
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/messages": {
      "get": {
        "operationId": "listMessages",
        "summary": "List logged messages",
        "tags": [
          "Logs"
        ],
        "description": "Messages queued, sent and received, newest first. counts apply every filter except direction, so they size the direction tabs.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "in",
                "out"
              ]
            },
            "in": "query",
            "name": "direction",
            "required": false
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "queued",
                "sent",
                "delivered",
                "read",
                "failed",
                "received"
              ]
            },
            "in": "query",
            "name": "status",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "tenantId",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "connectionId",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "q",
            "required": false,
            "description": "Contact, text, job id, clientRef or message id (case-insensitive)"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 60
            },
            "in": "query",
            "name": "limit",
            "required": false,
            "description": "Capped at 200"
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "logs:read"
            ]
          },
          {
            "apiKeyHeader": [
              "logs:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Logged messages, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Logged messages, newest first.",
                  "type": "object",
                  "properties": {
                    "messages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "tenantId": {
                            "type": "string"
                          },
                          "connectionId": {
                            "type": "string"
                          },
                          "direction": {
                            "type": "string",
                            "enum": [
                              "in",
                              "out"
                            ]
                          },
                          "contact": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string"
                          },
                          "body": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status": {
                            "type": "string"
                          },
                          "jobId": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "clientRef": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "messageId": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "events": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "status": {
                                  "type": "string"
                                },
                                "at": {
                                  "type": "string",
                                  "format": "date-time"
                                }
                              }
                            }
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "counts": {
                      "type": "object",
                      "properties": {
                        "all": {
                          "type": "number"
                        },
                        "in": {
                          "type": "number"
                        },
                        "out": {
                          "type": "number"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "messages": [
                    {
                      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
                      "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                      "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                      "direction": "out",
                      "contact": "5511988887777",
                      "type": "text",
                      "body": "Your appointment is confirmed for tomorrow at 10:00",
                      "status": "delivered",
                      "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
                      "clientRef": "crm-msg-1",
                      "messageId": "3EB0C767D26A1D8A3F52",
                      "error": null,
                      "events": [
                        {
                          "status": "queued",
                          "at": "2026-09-24T11:59:55.000Z"
                        },
                        {
                          "status": "sent",
                          "at": "2026-09-24T12:00:00.000Z"
                        },
                        {
                          "status": "delivered",
                          "at": "2026-09-24T12:00:02.000Z"
                        }
                      ],
                      "createdAt": "2026-09-24T11:59:55.000Z",
                      "updatedAt": "2026-09-24T12:00:02.000Z"
                    }
                  ],
                  "counts": {
                    "all": 1,
                    "in": 0,
                    "out": 1
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/webhooks/deliveries": {
      "get": {
        "operationId": "listWebhookDeliveries",
        "summary": "List webhook deliveries",
        "tags": [
          "Logs"
        ],
        "description": "One row per webhook event, newest first. counts ignore the state filter; stats cover every retained row (successRate 0-100, avgLatencyMs over delivered rows).",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "delivered",
                "retry",
                "dead"
              ]
            },
            "in": "query",
            "name": "state",
            "required": false
          },
          {
            "schema": {
              "type": "string"
            },
            "in": "query",
            "name": "tenantId",
            "required": false
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 60
            },
            "in": "query",
            "name": "limit",
            "required": false,
            "description": "Capped at 200"
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "logs:read"
            ]
          },
          {
            "apiKeyHeader": [
              "logs:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook deliveries, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Webhook deliveries, newest first.",
                  "type": "object",
                  "properties": {
                    "deliveries": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "tenantId": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "connectionId": {
                            "type": "string"
                          },
                          "eventType": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "delivered",
                              "retry",
                              "dead"
                            ]
                          },
                          "httpStatus": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "latencyMs": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "attempts": {
                            "type": "number"
                          },
                          "maxAttempts": {
                            "type": "number"
                          },
                          "nextAttemptAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "signed": {
                            "type": "boolean"
                          },
                          "payload": {},
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    },
                    "counts": {
                      "type": "object",
                      "properties": {
                        "all": {
                          "type": "number"
                        },
                        "delivered": {
                          "type": "number"
                        },
                        "retry": {
                          "type": "number"
                        },
                        "dead": {
                          "type": "number"
                        }
                      }
                    },
                    "stats": {
                      "type": "object",
                      "properties": {
                        "successRate": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "avgLatencyMs": {
                          "type": [
                            "number",
                            "null"
                          ]
                        }
                      }
                    }
                  }
                },
                "example": {
                  "deliveries": [
                    {
                      "id": "9c2d5e6f-7a8b-4c9d-8e0f-3a4b5c6d7e8f",
                      "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                      "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                      "eventType": "message.delivery",
                      "url": "https://crm.example.com/api/whatsapp/events",
                      "state": "delivered",
                      "httpStatus": 200,
                      "error": null,
                      "latencyMs": 120,
                      "attempts": 1,
                      "maxAttempts": 6,
                      "nextAttemptAt": null,
                      "signed": true,
                      "payload": {
                        "type": "message.delivery",
                        "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                        "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                        "externalId": "shop-42",
                        "timestamp": "2026-09-24T12:00:02.000Z",
                        "data": {
                          "messageId": "3EB0C767D26A1D8A3F52",
                          "status": "delivered",
                          "recipient": "5511988887777",
                          "jid": "5511988887777@s.whatsapp.net",
                          "phone": "+5511988887777",
                          "clientRef": "crm-msg-1"
                        }
                      },
                      "createdAt": "2026-09-24T12:00:02.000Z",
                      "updatedAt": "2026-09-24T12:00:02.000Z"
                    }
                  ],
                  "counts": {
                    "all": 1,
                    "delivered": 1,
                    "retry": 0,
                    "dead": 0
                  },
                  "stats": {
                    "successRate": 100,
                    "avgLatencyMs": 120
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/webhooks/deliveries/resend-dead": {
      "post": {
        "operationId": "resendDeadWebhookDeliveries",
        "summary": "Resend every dead webhook delivery",
        "tags": [
          "Logs"
        ],
        "description": "Queues every delivery in state dead of the caller's tenants again (every tenant's for the platform; at most 1000 per call).",
        "security": [
          {
            "apiKeyBearer": [
              "webhooks:write"
            ]
          },
          {
            "apiKeyHeader": [
              "webhooks:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "How many deliveries were queued again.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "How many deliveries were queued again.",
                  "type": "object",
                  "properties": {
                    "requeued": {
                      "type": "number"
                    }
                  }
                },
                "example": {
                  "requeued": 3
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/webhooks/deliveries/{id}/resend": {
      "post": {
        "operationId": "resendWebhookDelivery",
        "summary": "Resend a webhook delivery",
        "tags": [
          "Logs"
        ],
        "description": "Queues the delivery again, due now, with a fresh attempt budget. Works for dead and retrying deliveries; a delivered one answers 409.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "in": "path",
            "name": "id",
            "required": true
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "webhooks:write"
            ]
          },
          {
            "apiKeyHeader": [
              "webhooks:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The delivery, queued again.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "tenantId": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "connectionId": {
                      "type": "string"
                    },
                    "eventType": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "delivered",
                        "retry",
                        "dead"
                      ]
                    },
                    "httpStatus": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "error": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "latencyMs": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "attempts": {
                      "type": "number"
                    },
                    "maxAttempts": {
                      "type": "number"
                    },
                    "nextAttemptAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "signed": {
                      "type": "boolean"
                    },
                    "payload": {},
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "description": "The delivery, queued again."
                },
                "example": {
                  "id": "9c2d5e6f-7a8b-4c9d-8e0f-3a4b5c6d7e8f",
                  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                  "eventType": "message.delivery",
                  "url": "https://crm.example.com/api/whatsapp/events",
                  "state": "retry",
                  "httpStatus": 500,
                  "error": "HTTP 500",
                  "latencyMs": 80,
                  "attempts": 0,
                  "maxAttempts": 6,
                  "nextAttemptAt": "2026-09-24T12:00:00.000Z",
                  "signed": true,
                  "payload": {
                    "type": "message.delivery",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:02.000Z",
                    "data": {
                      "messageId": "3EB0C767D26A1D8A3F52",
                      "status": "delivered",
                      "recipient": "5511988887777",
                      "jid": "5511988887777@s.whatsapp.net",
                      "phone": "+5511988887777",
                      "clientRef": "crm-msg-1"
                    }
                  },
                  "createdAt": "2026-09-24T12:00:02.000Z",
                  "updatedAt": "2026-09-24T12:00:02.000Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "missingVariables": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/usage/daily": {
      "get": {
        "operationId": "getDailyUsage",
        "summary": "Daily message totals across the caller's tenants (every tenant for the platform)",
        "tags": [
          "Usage"
        ],
        "description": "One entry per UTC day, zero days included, oldest first; today is the last entry.",
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 90,
              "default": 14
            },
            "in": "query",
            "name": "days",
            "required": false
          }
        ],
        "security": [
          {
            "apiKeyBearer": [
              "usage:read"
            ]
          },
          {
            "apiKeyHeader": [
              "usage:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Daily totals, oldest first.",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Daily totals, oldest first.",
                  "type": "object",
                  "properties": {
                    "days": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "date": {
                            "type": "string",
                            "description": "YYYY-MM-DD (UTC)"
                          },
                          "sent": {
                            "type": "number"
                          },
                          "received": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "days": [
                    {
                      "date": "2026-09-23",
                      "sent": 42,
                      "received": 17
                    },
                    {
                      "date": "2026-09-24",
                      "sent": 12,
                      "received": 5
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.apiwpp.com",
      "description": "This gateway"
    }
  ],
  "webhooks": {
    "connection.status": {
      "post": {
        "operationId": "onConnectionStatus",
        "tags": [
          "Webhooks"
        ],
        "summary": "The connection opened, closed or was restricted",
        "description": "data of connection.status: the socket opened or closed, or WhatsApp changed what the account may do. A close the gateway reports carries why (reason) and whether the gateway reconnects on its own (willReconnect). willReconnect true (transient, restart_required) means the gateway keeps retrying with backoff until it opens again, reported by the next status open; false means it stopped and waits for a human: a new QR (logged_out, qr_not_scanned) or an explicit reconnect (replaced, manual). passkey_required: the QR was scanned but pairing never completed because WhatsApp asked the phone for a passkey; status is close, there is no phoneNumber (the link never confirmed one), and no more QR codes are generated until the connection is connected again. reachout_timelock: WhatsApp put the account under a reach-out timelock (sent after a 463 or a WhatsApp notification; status is the current one, normally open); until reachoutTimelock.endsAt (or a reachout_timelock_lifted event) every queued send is dropped as message.send_failed reason reachout_timelocked instead of being attempted. reason is absent on an open; willReconnect and statusCode are present only on a close with one of the first six reasons.\n\nDelivered at least once: apply it idempotently.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookToken"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEventEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "connection.status"
                      },
                      "data": {
                        "$ref": "#/components/schemas/ConnectionStatusEvent"
                      }
                    }
                  }
                ]
              },
              "examples": {
                "example1": {
                  "summary": "Opened",
                  "value": {
                    "type": "connection.status",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "status": "open",
                      "phoneNumber": "5511900000001"
                    }
                  }
                },
                "example2": {
                  "summary": "Closed, reconnecting on its own",
                  "value": {
                    "type": "connection.status",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "status": "close",
                      "phoneNumber": "5511900000001",
                      "reason": "transient",
                      "willReconnect": true,
                      "statusCode": 503
                    }
                  }
                },
                "example3": {
                  "summary": "Logged out on the phone",
                  "value": {
                    "type": "connection.status",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "status": "close",
                      "phoneNumber": "5511900000001",
                      "reason": "logged_out",
                      "willReconnect": false,
                      "statusCode": 401
                    }
                  }
                },
                "example4": {
                  "summary": "Reach-out timelock",
                  "value": {
                    "type": "connection.status",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "status": "open",
                      "phoneNumber": "5511900000001",
                      "reason": "reachout_timelock",
                      "reachoutTimelock": {
                        "active": true,
                        "endsAt": "2026-09-25T12:00:00.000Z",
                        "enforcementType": "BIZ_QUALITY"
                      }
                    }
                  }
                },
                "example5": {
                  "summary": "Pairing stalled on a passkey",
                  "value": {
                    "type": "connection.status",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "status": "close",
                      "reason": "passkey_required"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. The response body is ignored."
          },
          "3XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "4XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "5XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          }
        },
        "security": []
      }
    },
    "message.incoming": {
      "post": {
        "operationId": "onMessageIncoming",
        "tags": [
          "Webhooks"
        ],
        "summary": "Someone wrote to the number",
        "description": "data of message.incoming: a message someone sent to the number, in a 1:1 chat or a group it is in (then jid is the group and phone is null).\n\nDelivered at least once: apply it idempotently.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookToken"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEventEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "message.incoming"
                      },
                      "data": {
                        "$ref": "#/components/schemas/MessageIncomingEvent"
                      }
                    }
                  }
                ]
              },
              "examples": {
                "example1": {
                  "summary": "Text",
                  "value": {
                    "type": "message.incoming",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "from": "5511988887777@s.whatsapp.net",
                      "to": "5511900000001:7@s.whatsapp.net",
                      "body": "Olá! Tem horário amanhã às 10h?",
                      "timestamp": 1790251200,
                      "raw": {
                        "key": {
                          "remoteJid": "5511988887777@s.whatsapp.net",
                          "fromMe": false,
                          "id": "IN-TEXT-1"
                        },
                        "message": {
                          "conversation": "Olá! Tem horário amanhã às 10h?"
                        },
                        "messageTimestamp": 1790251200,
                        "pushName": "Maria"
                      },
                      "resolvedPhone": "5511988887777",
                      "jid": "5511988887777@s.whatsapp.net",
                      "phone": "+5511988887777"
                    }
                  }
                },
                "example2": {
                  "summary": "Image with a signed media URL",
                  "value": {
                    "type": "message.incoming",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "from": "5511988887777@s.whatsapp.net",
                      "to": "5511900000001:7@s.whatsapp.net",
                      "body": "Is this haircut possible?",
                      "timestamp": 1790251200,
                      "raw": {
                        "key": {
                          "remoteJid": "5511988887777@s.whatsapp.net",
                          "fromMe": false,
                          "id": "IN-IMG-1"
                        }
                      },
                      "media": {
                        "type": "image",
                        "url": "https://gateway.example.com/media/8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f/IN-IMG-1.jpg?exp=1790337600&sig=zPUxL8vvbncrSGOkg72U9hOK-6GOcrWOlHSYjjv4sHs",
                        "mimetype": "image/jpeg",
                        "fileName": "IN-IMG-1.jpg",
                        "fileSize": 48213,
                        "expiresAt": 1790337600000
                      },
                      "resolvedPhone": "5511988887777",
                      "jid": "5511988887777@s.whatsapp.net",
                      "phone": "+5511988887777"
                    }
                  }
                },
                "example3": {
                  "summary": "From a LID not resolved yet (see contact.resolved)",
                  "value": {
                    "type": "message.incoming",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "from": "11122233344455@lid",
                      "to": "5511900000001:7@s.whatsapp.net",
                      "body": "Can I bring my son too?",
                      "timestamp": 1790251200,
                      "raw": {
                        "key": {
                          "remoteJid": "11122233344455@lid",
                          "fromMe": false,
                          "id": "IN-TEXT-2"
                        }
                      },
                      "jid": "11122233344455@lid",
                      "phone": null
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. The response body is ignored."
          },
          "3XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "4XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "5XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          }
        },
        "security": []
      }
    },
    "message.outgoing": {
      "post": {
        "operationId": "onMessageOutgoing",
        "tags": [
          "Webhooks"
        ],
        "summary": "The number sent a message (opt-in: emitOutgoing)",
        "description": "data of message.outgoing: a message the paired number sent in a 1:1 chat. Emitted once per messageId, and only to a tenant created or patched with emitOutgoing: true (off by default). origin API = the gateway sent it through POST /connections/:id/send (the id was recorded before sending, so this is a lookup, never a guess); origin PHONE = typed on the phone or another linked device. Groups, status broadcasts and newsletters are not reported.\n\nDelivered at least once: apply it idempotently.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookToken"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEventEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "message.outgoing"
                      },
                      "data": {
                        "$ref": "#/components/schemas/MessageOutgoingEvent"
                      }
                    }
                  }
                ]
              },
              "examples": {
                "example1": {
                  "summary": "Sent through the API",
                  "value": {
                    "type": "message.outgoing",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "messageId": "3EB0C767D26A1D8A3F52",
                      "origin": "API",
                      "clientRef": "crm-msg-1",
                      "to": "5511988887777@s.whatsapp.net",
                      "toE164": "+5511988887777",
                      "body": "Your appointment is confirmed for tomorrow at 10:00",
                      "timestamp": 1790251200,
                      "jid": "5511988887777@s.whatsapp.net",
                      "phone": "+5511988887777"
                    }
                  }
                },
                "example2": {
                  "summary": "Typed on the phone",
                  "value": {
                    "type": "message.outgoing",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "messageId": "3EB0A1B2C3D4E5F60718",
                      "origin": "PHONE",
                      "clientRef": null,
                      "to": "5511988887777@s.whatsapp.net",
                      "toE164": "+5511988887777",
                      "body": "See you tomorrow!",
                      "timestamp": 1790251200,
                      "jid": "5511988887777@s.whatsapp.net",
                      "phone": "+5511988887777"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. The response body is ignored."
          },
          "3XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "4XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "5XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          }
        },
        "security": []
      }
    },
    "message.delivery": {
      "post": {
        "operationId": "onMessageDelivery",
        "tags": [
          "Webhooks"
        ],
        "summary": "A message the number sent changed status",
        "description": "data of message.delivery: a status change of a message the number sent.\n\nDelivered at least once: apply it idempotently.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookToken"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEventEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "message.delivery"
                      },
                      "data": {
                        "$ref": "#/components/schemas/MessageDeliveryEvent"
                      }
                    }
                  }
                ]
              },
              "examples": {
                "example1": {
                  "summary": "Delivered",
                  "value": {
                    "type": "message.delivery",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "messageId": "3EB0C767D26A1D8A3F52",
                      "status": "delivered",
                      "recipient": "5511988887777",
                      "clientRef": "crm-msg-1",
                      "jid": "5511988887777@s.whatsapp.net",
                      "phone": "+5511988887777"
                    }
                  }
                },
                "example2": {
                  "summary": "Refused as a reach-out (463)",
                  "value": {
                    "type": "message.delivery",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "messageId": "3EB0C767D26A1D8A3F52",
                      "status": "failed",
                      "recipient": "5511988887777",
                      "clientRef": "crm-msg-1",
                      "reason": "reachout_timelocked",
                      "jid": "5511988887777@s.whatsapp.net",
                      "phone": "+5511988887777"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. The response body is ignored."
          },
          "3XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "4XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "5XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          }
        },
        "security": []
      }
    },
    "message.send_failed": {
      "post": {
        "operationId": "onMessageSendFailed",
        "tags": [
          "Webhooks"
        ],
        "summary": "A queued send with a clientRef will not happen",
        "description": "data of message.send_failed: a job queued by POST /connections/:id/send WITH a clientRef that the gateway gave up on (attempts exhausted, its lease expired on the last attempt, the number is not on WhatsApp, or the account is under a WhatsApp reach-out timelock and the send was refused without being attempted). Never emitted for a job without a clientRef. A retry with the same clientRef keeps answering duplicate, so this is the consumer's only signal that the accepted send will not happen; a deliberate resend uses a new clientRef. If an echo or a delivery status for the same clientRef arrives later, that proof wins.\n\nDelivered at least once: apply it idempotently.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookToken"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEventEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "message.send_failed"
                      },
                      "data": {
                        "$ref": "#/components/schemas/MessageSendFailedEvent"
                      }
                    }
                  }
                ]
              },
              "examples": {
                "example1": {
                  "summary": "Not on WhatsApp",
                  "value": {
                    "type": "message.send_failed",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "clientRef": "crm-msg-1",
                      "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
                      "messageId": null,
                      "to": "5511988887777",
                      "reason": "not_on_whatsapp",
                      "attempts": 1,
                      "jid": "5511988887777@s.whatsapp.net",
                      "phone": "+5511988887777"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. The response body is ignored."
          },
          "3XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "4XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "5XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          }
        },
        "security": []
      }
    },
    "message.reaction": {
      "post": {
        "operationId": "onMessageReaction",
        "tags": [
          "Webhooks"
        ],
        "summary": "Someone reacted to a message",
        "description": "data of message.reaction.\n\nDelivered at least once: apply it idempotently.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookToken"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEventEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "message.reaction"
                      },
                      "data": {
                        "$ref": "#/components/schemas/MessageReactionEvent"
                      }
                    }
                  }
                ]
              },
              "examples": {
                "example1": {
                  "summary": "Reaction added",
                  "value": {
                    "type": "message.reaction",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "messageId": "3EB0C767D26A1D8A3F52",
                      "from": "5511988887777",
                      "emoji": "👍",
                      "jid": "5511988887777@s.whatsapp.net",
                      "phone": "+5511988887777"
                    }
                  }
                },
                "example2": {
                  "summary": "Reaction removed",
                  "value": {
                    "type": "message.reaction",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "messageId": "3EB0C767D26A1D8A3F52",
                      "from": "5511988887777",
                      "emoji": "",
                      "jid": "5511988887777@s.whatsapp.net",
                      "phone": "+5511988887777"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. The response body is ignored."
          },
          "3XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "4XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "5XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          }
        },
        "security": []
      }
    },
    "contact.resolved": {
      "post": {
        "operationId": "onContactResolved",
        "tags": [
          "Webhooks"
        ],
        "summary": "A sender known only by LID now has a phone",
        "description": "data of contact.resolved. A sender that earlier reached this tenant as a LID with phone: null now has a known phone number. Emitted once per pending LID per connection, only to the tenant that received those messages. Re-attribute every earlier event whose jid equals data.lid.\n\nDelivered at least once: apply it idempotently.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookToken"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEventEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "contact.resolved"
                      },
                      "data": {
                        "$ref": "#/components/schemas/ContactResolvedEvent"
                      }
                    }
                  }
                ]
              },
              "examples": {
                "example1": {
                  "summary": "Resolved",
                  "value": {
                    "type": "contact.resolved",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "lid": "11122233344455@lid",
                      "jid": "5511988887777@s.whatsapp.net",
                      "phone": "+5511988887777",
                      "firstSeenAt": "2026-09-24T12:00:00.000Z",
                      "messageCount": 2,
                      "source": "lid-mapping"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. The response body is ignored."
          },
          "3XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "4XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "5XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          }
        },
        "security": []
      }
    },
    "group.joined": {
      "post": {
        "operationId": "onGroupJoined",
        "tags": [
          "Webhooks"
        ],
        "summary": "The number joined a group",
        "description": "data of group.joined: the number joined or was added to a group. Also sent once per group the number is already in when its connection first opens in this gateway process (not again on reconnects).\n\nDelivered at least once: apply it idempotently.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookToken"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEventEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "group.joined"
                      },
                      "data": {
                        "$ref": "#/components/schemas/GroupJoinedEvent"
                      }
                    }
                  }
                ]
              },
              "examples": {
                "example1": {
                  "summary": "Joined",
                  "value": {
                    "type": "group.joined",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "groupId": "120363040000000001@g.us",
                      "groupName": "Barber team",
                      "participantCount": 3
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. The response body is ignored."
          },
          "3XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "4XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "5XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          }
        },
        "security": []
      }
    },
    "group.left": {
      "post": {
        "operationId": "onGroupLeft",
        "tags": [
          "Webhooks"
        ],
        "summary": "The number was removed from a group",
        "description": "data of group.left: the number was removed from a group.\n\nDelivered at least once: apply it idempotently.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookToken"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEventEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "group.left"
                      },
                      "data": {
                        "$ref": "#/components/schemas/GroupLeftEvent"
                      }
                    }
                  }
                ]
              },
              "examples": {
                "example1": {
                  "summary": "Removed",
                  "value": {
                    "type": "group.left",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "groupId": "120363040000000001@g.us",
                      "reason": "kicked"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. The response body is ignored."
          },
          "3XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "4XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "5XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          }
        },
        "security": []
      }
    },
    "group.updated": {
      "post": {
        "operationId": "onGroupUpdated",
        "tags": [
          "Webhooks"
        ],
        "summary": "A group of the number changed",
        "description": "data of group.updated: a group the number is in changed.\n\nDelivered at least once: apply it idempotently.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookToken"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEventEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "group.updated"
                      },
                      "data": {
                        "$ref": "#/components/schemas/GroupUpdatedEvent"
                      }
                    }
                  }
                ]
              },
              "examples": {
                "example1": {
                  "summary": "Renamed",
                  "value": {
                    "type": "group.updated",
                    "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
                    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
                    "externalId": "shop-42",
                    "timestamp": "2026-09-24T12:00:00.000Z",
                    "data": {
                      "groupId": "120363040000000001@g.us",
                      "groupName": "Barber team 2026"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. The response body is ignored."
          },
          "3XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "4XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          },
          "5XX": {
            "description": "A failed attempt, like a network error or no answer within 10 s (redirects are never followed). It is retried with backoff, 6 attempts in all, then dead-lettered: see GET /webhooks/deliveries to resend it."
          }
        },
        "security": []
      }
    }
  },
  "security": [
    {
      "apiKeyBearer": []
    },
    {
      "apiKeyHeader": []
    }
  ],
  "tags": [
    {
      "name": "Connections",
      "description": "WhatsApp numbers: list them, pair by QR code, route them through your own proxy, disconnect, log out."
    },
    {
      "name": "Messages",
      "description": "Queue messages and reactions; inspect and cancel the send queue."
    },
    {
      "name": "Contacts",
      "description": "Whether numbers are on WhatsApp, and contact profiles."
    },
    {
      "name": "Templates",
      "description": "Reusable messages with {{variables}}, per connection."
    },
    {
      "name": "Media",
      "description": "Inbound media files, fetched through the signed URLs webhooks carry."
    },
    {
      "name": "Tenants",
      "description": "Your tenants: webhook settings, their connections and connection history."
    },
    {
      "name": "API keys",
      "description": "A tenant's API keys: create (shown once), list, revoke, rotate."
    },
    {
      "name": "Usage",
      "description": "Messages sent and received, against the plan limits."
    },
    {
      "name": "Logs",
      "description": "Message log and webhook delivery log, with redelivery."
    },
    {
      "name": "Account",
      "description": "The calling credential: its organization, the scopes it holds and its tenants."
    },
    {
      "name": "Webhooks",
      "description": "Events the gateway POSTs to the tenant's webhookBaseUrl."
    }
  ]
}
