IntegrationsService

Manages third-party notification channel integrations for an organization — recipient reachability, data-residency region policies, monthly cost caps, generic webhook configuration, and channel connect links. Email is live today; Slack, Telegram, SMS, and generic webhooks are rolling out. Third-party channels are additive to push: they carry only a deeplink notification, and message content stays in the platform.

Requests to this service carry an explicit org_id, which must match the caller’s organization. Cross-org access is denied with PERMISSION_DENIED.

Methods

Method	Description
DispatchToChannel	Dispatch a single rendered message to one channel (internal)
UpsertReachability	Record a recipient identifier for a (user, channel) pair
RemoveReachability	Remove a recipient identifier
GetReachability	Get reachability metadata for a (user, channel) pair
ListReachabilityForUser	List per-channel reachability for a user
GetRegionPolicy	Get the per-channel region allowlist
SetRegionPolicy	Set the per-channel region allowlist
GetCostCapPolicy	Get the current month’s cost cap and spend
SetCostCapPolicy	Set the current month’s cost cap
GetOrgWebhookConfig	Get the org’s webhook channel configuration
SetOrgWebhookConfig	Set the org’s webhook channel configuration
CreateChannelConnectLink	Mint an opt-in link to connect a follow-style channel

DispatchToChannel

Dispatch a single rendered message to one channel for one recipient. Idempotent on dispatch_id: if the same dispatch was already sent, the prior receipt is returned with status DISPATCH_STATUS_DEDUPED instead of contacting the provider again.

Authorization: Internal service only

Request: DispatchToChannelRequest

Field	Type	Description
dispatch_id	string	Idempotency key. Stable across retries.
org_id	string	Organization ID.
user_id	string	Recipient user ID.
channel	ChannelName	Channel to dispatch through.
template_id	string	Template to render before dispatch.
template_vars	map<string, string>	Per-recipient template variables.
locale	string	BCP-47 locale used to select the template translation.
region_constraint	string	Optional region the dispatch must originate from. Unset means no constraint.

Response: DispatchToChannelResponse

Field	Type	Description
dispatch_id	string	Echoes the request’s dispatch_id.
status	DispatchStatus	Terminal outcome of this call.
failure_reason	string	Human-readable failure reason. Set only when status is DISPATCH_STATUS_FAILED.

UpsertReachability

Record a recipient identifier (email address, phone number, chat ID, etc.) for a (user, channel) pair. The identifier is encrypted at rest server-side and is never logged or returned by any read RPC. An audit event is recorded before the write commits.

Authorization: Admin only

Request: UpsertReachabilityRequest

Field	Type	Description
org_id	string	Organization ID. Must match the caller’s organization.
user_id	string	User the identifier belongs to.
channel	ChannelName	Channel this identifier is for.
identifier_plaintext	string	The recipient identifier. Encrypted at rest; treat as sensitive.
region_constraint	string	Optional region this user’s data must remain in (e.g. eu-west-1). Recorded at write time; enforced at dispatch.

Response: UpsertReachabilityResponse

Field	Type	Description
reachability	Reachability	Metadata for the upserted entry. The identifier itself is not returned.

RemoveReachability

Remove a recipient identifier. Idempotent — removing a pair that has no entry returns success with removed = false. An audit event is recorded before the deletion.

Authorization: Admin only

Request: RemoveReachabilityRequest

Field	Type	Description
org_id	string	Organization ID. Must match the caller’s organization.
user_id	string	User ID.
channel	ChannelName	Channel to remove the identifier for.

Response: RemoveReachabilityResponse

Field	Type	Description
removed	bool	True if an entry was deleted. False if none existed (idempotent success).

GetReachability

Get reachability metadata for a single (user, channel) pair. Returns NOT_FOUND if no entry exists. The recipient identifier itself is never returned.

Authorization: Admin only

Request: GetReachabilityRequest

Field	Type	Description
org_id	string	Organization ID. Must match the caller’s organization.
user_id	string	User ID.
channel	ChannelName	Channel to look up.

Response: GetReachabilityResponse

Field	Type	Description
reachability	Reachability	The reachability metadata.

ListReachabilityForUser

List one Reachability entry per channel configured for a user. Intended for per-user channel matrix views — it only reports which channels are configured, never the identifiers themselves.

Authorization: Admin only

Request: ListReachabilityForUserRequest

Field	Type	Description
org_id	string	Organization ID. Must match the caller’s organization.
user_id	string	User ID.

Response: ListReachabilityForUserResponse

Field	Type	Description
reachabilities	Reachability[]	One entry per channel configured for the user.

GetRegionPolicy

Get the per-(organization, channel) region allowlist. Always returns a policy — an empty allowed_regions list means “no policy configured”, not “no regions allowed”.

Authorization: Admin only

Request: GetRegionPolicyRequest

Field	Type	Description
org_id	string	Organization ID. Must match the caller’s organization.
channel	ChannelName	Channel the policy applies to.

Response: GetRegionPolicyResponse

Field	Type	Description
policy	RegionPolicy	The region policy. Always populated.

SetRegionPolicy

Set the per-(organization, channel) region allowlist. Passing an empty allowed_regions list clears the policy.

Authorization: Admin only

Request: SetRegionPolicyRequest

Field	Type	Description
org_id	string	Organization ID. Must match the caller’s organization.
channel	ChannelName	Channel the policy applies to.
allowed_regions	string[]	Region identifiers (e.g. eu-west-1). Empty list clears the policy.

Response: SetRegionPolicyResponse

Field	Type	Description
policy	RegionPolicy	The updated policy.

GetCostCapPolicy

Get the cost-cap state for the current calendar month (UTC). When no cap has been set for the period, the channel’s default cap is returned with used_micros = 0 — this call never returns NOT_FOUND.

Authorization: Admin only

Request: GetCostCapPolicyRequest

Field	Type	Description
org_id	string	Organization ID. Must match the caller’s organization.
channel	ChannelName	Channel the cap applies to.

Response: GetCostCapPolicyResponse

Field	Type	Description
org_id	string	Organization ID.
channel	ChannelName	Channel.
cap_micros	int64	Current period’s cap in micros (1/1,000,000 of a USD).
used_micros	int64	Current period’s accumulated spend in micros.
period_yyyymm	int32	Calendar-month period as an integer (e.g. 202605 for May 2026).

SetCostCapPolicy

Set the cost cap for the current calendar month. Future periods inherit the most recent value until the next call.

Authorization: Admin only

Request: SetCostCapPolicyRequest

Field	Type	Description
org_id	string	Organization ID. Must match the caller’s organization.
channel	ChannelName	Channel the cap applies to.
cap_micros	int64	New cap in micros (1/1,000,000 of a USD).

Response: SetCostCapPolicyResponse

Field	Type	Description
org_id	string	Organization ID.
channel	ChannelName	Channel.
cap_micros	int64	The cap that was set.
used_micros	int64	Current period’s accumulated spend in micros.
period_yyyymm	int32	Calendar-month period as an integer.

GetOrgWebhookConfig

Get the organization’s generic-webhook channel configuration. The signing secret is write-only and never returned — has_secret reports whether one is set. Returns an empty-URL config when none exists, never NOT_FOUND.

Authorization: Admin only

Request: GetOrgWebhookConfigRequest

Field	Type	Description
org_id	string	Organization ID. Must match the caller’s organization.

Response: GetOrgWebhookConfigResponse

Field	Type	Description
org_id	string	Organization ID.
url	string	Destination URL Pidgr POSTs notification events to. Empty when no configuration exists.
enabled	bool	Whether dispatch via the WEBHOOK channel is enabled for the org.
has_secret	bool	Whether a signing secret is currently configured.
created_at	Timestamp	When the configuration was created.
updated_at	Timestamp	When the configuration was last updated.

SetOrgWebhookConfig

Set the organization’s generic-webhook channel configuration. The destination URL is validated before persisting (https scheme; non-private, non-loopback host — failures return INVALID_ARGUMENT), and the secret is encrypted at rest. Setting a new secret rotates it; leaving it unset keeps the existing one.

Authorization: Admin only

Request: SetOrgWebhookConfigRequest

Field	Type	Description
org_id	string	Organization ID. Must match the caller’s organization.
url	string	Destination URL. Must use https and resolve to a public host.
enabled	bool	Whether dispatch via the WEBHOOK channel is enabled.
secret	string	Shared secret used for the X-Pidgr-Signature HMAC-SHA256 header. Write-only; 16–256 bytes when set. Unset keeps the current secret.

Response: SetOrgWebhookConfigResponse

Field	Type	Description
org_id	string	Organization ID.
url	string	The configured destination URL.
enabled	bool	Whether the WEBHOOK channel is enabled.
has_secret	bool	Whether a signing secret is configured.
created_at	Timestamp	When the configuration was created.
updated_at	Timestamp	When the configuration was last updated.

CreateChannelConnectLink

Mint a short-lived, signed opt-in link a user follows to bind a follow-style third-party channel to their account: CHANNEL_NAME_TELEGRAM (bot follow), CHANNEL_NAME_SLACK (OAuth), or CHANNEL_NAME_LINE (follow code). Any other channel is rejected with INVALID_ARGUMENT. If the requested channel is not yet configured for the organization, the call returns FAILED_PRECONDITION.

Authorization: Authenticated user — the minted token binds the caller’s own account. A user_id that differs from the caller is rejected with PERMISSION_DENIED.

Request: CreateChannelConnectLinkRequest

Field	Type	Description
org_id	string	Organization ID. Must match the caller’s organization.
user_id	string	User ID the channel identifier will be bound to. Must resolve to the caller.
channel	ChannelName	Channel to connect. One of CHANNEL_NAME_TELEGRAM, CHANNEL_NAME_SLACK, CHANNEL_NAME_LINE.

Response: CreateChannelConnectLinkResponse

Field	Type	Description
connect_url	string	The link the user follows (e.g. a Telegram bot-follow URL, Slack OAuth authorize URL, or LINE follow URL).
token	string	The raw opt-in token embedded in connect_url, surfaced separately for QR codes or copy buttons. Opaque — do not parse or mutate.
expires_at	Timestamp	When the token expires. After this time the user must request a fresh link.

Reachability Message

A single reachability entry. The recipient identifier is never returned over the wire — only metadata.

Field	Type	Description
id	string	Server-assigned entry identifier.
org_id	string	Organization that owns the entry.
user_id	string	User the entry is for.
channel	ChannelName	Channel this entry stores a contact identifier for.
created_at	Timestamp	When the entry was first written.
updated_at	Timestamp	When the entry was last upserted.
region_constraint	string	Optional region this user’s data must remain in. Unset means no constraint. Enforced at dispatch time.

RegionPolicy Message

Per-(organization, channel) region allowlist used to enforce data-residency policy at dispatch time.

Field	Type	Description
org_id	string	Organization ID.
channel	ChannelName	Channel the policy applies to.
allowed_regions	string[]	Region identifiers (e.g. eu-west-1). Empty list means no policy configured — dispatch is not blocked.
updated_at	Timestamp	When the policy was last updated.

DispatchStatus Enum

Terminal outcome of a single DispatchToChannel call. Distinct from the richer ChannelEventStatus on the ChannelEventsService page, which models every state transition of a dispatch.

Value	Number	Description
DISPATCH_STATUS_UNSPECIFIED	0	Unspecified
DISPATCH_STATUS_SENT	1	The channel provider accepted the message for delivery
DISPATCH_STATUS_FAILED	2	Terminal error (e.g. recipient blocked); no retries — consult failure_reason
DISPATCH_STATUS_DEDUPED	3	A prior successful dispatch with the same dispatch_id was found; the prior receipt was returned

See the ChannelEventsService page for the ChannelName enum shared by both services.