SynapSynapDocs
Hub REST API

Messaging

The Messaging operations of the Hub REST API (17 operations).

For BuildersOpen-source podSynap CloudGenerated from Synap-core/backend@c31e261ab (main)

Land a provider-agnostic inbound message into the pod

POST
/messaging/inbound

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
provider*string
Length1 <= length
text?string
Lengthlength <= 50000
Default""
messageId*string
Length1 <= length
externalId?string
Length1 <= length
participantEmail?string
Formatemail
participant?string
Length1 <= length
participantExternalId?string
Length1 <= length
subject?string
Lengthlength <= 2000
sentAt?string
workspaceId?string
Formatuuid
projectId?string
Formatuuid
userId?string
Formatuuid
attachments?array<>
Itemsitems <= 8
headerMessageId?string
Lengthlength <= 998
inReplyTo?string
Lengthlength <= 998
references?array<>
Itemsitems <= 50

Response Body

Record result

application/json
  1. response
recorded*boolean
channelId*string
deduped*boolean
Example Request
curl -X POST 'https://pod.example.com/api/hub/messaging/inbound' \  -H 'Content-Type: application/json' \  -d '{  "provider": "string",  "messageId": "string"}'
Example Response
{  "recorded": true,  "channelId": "string",  "deduped": true}

List connected messaging accounts for the current user

GET
/messaging/accounts

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Response Body

List of connected accounts

application/json
  1. response
[index: integer]?
Example Request
curl -X GET 'https://pod.example.com/api/hub/messaging/accounts'
Example Response
[  {    "id": "string",    "externalId": "string",    "provider": "string",    "displayName": "string",    "status": "connected"  }]

Get hosted auth URL for connecting a new account

GET
/messaging/auth-url

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Query Parameters

redirectUrl*string
provider?string

Response Body

Auth URL

application/json
  1. response
url*string
Example Request
curl -X GET 'https://pod.example.com/api/hub/messaging/auth-url?redirectUrl=string'
Example Response
{  "url": "string"}

Sync live accounts from the connector into the database

POST
/messaging/accounts/sync

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Response Body

Sync result

application/json
  1. response
synced*number
Example Request
curl -X POST 'https://pod.example.com/api/hub/messaging/accounts/sync'
Example Response
{  "synced": 0}

Get current messaging connector config state (masked)

GET
/messaging/service-config

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Response Body

Config state

application/json
  1. response
configured*boolean
source*|
Value in"vault""workspace_settings""env"null
dsn*string|null
hasApiKey*boolean
hasWebhookSecret*boolean
migration*
Example Request
curl -X GET 'https://pod.example.com/api/hub/messaging/service-config'
Example Response200
{  "configured": true,  "source": "vault",  "dsn": "string",  "hasApiKey": true,  "hasWebhookSecret": true,  "migration": {    "available": true,    "hasDsn": true,    "hasApiKey": true  }}

Store Unipile connector credentials in the vault

POST
/messaging/service-config

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
dsn*string
apiKey*string
webhookSecret?string

Response Body

Stored successfully

application/json
  1. response
ok*boolean
Example Request
curl -X POST 'https://pod.example.com/api/hub/messaging/service-config' \  -H 'Content-Type: application/json' \  -d '{  "dsn": "string",  "apiKey": "string"}'
Example Response
{  "ok": true}

Migrate workspace settings messaging credentials to vault

POST
/messaging/service-config/migrate

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Response Body

Migrated

application/json
  1. response
ok*boolean
Example Request
curl -X POST 'https://pod.example.com/api/hub/messaging/service-config/migrate'
Example Response
{  "ok": true}

Disconnect a messaging account

DELETE
/messaging/accounts/{accountId}

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

accountId*string

Response Body

Account disconnected

application/json
  1. response
success*boolean
Example Request
curl -X DELETE 'https://pod.example.com/api/hub/messaging/accounts/string'
Example Response
{  "success": true}

List conversations — entity-linked or browse mode

GET
/messaging/conversations

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Query Parameters

entityId?string
contactEntityId?string

Response Body

Conversations

application/json
  1. response
conversations*array<|>
Example Request
curl -X GET 'https://pod.example.com/api/hub/messaging/conversations'
Example Response
{  "conversations": [    {      "channelId": "string",      "externalThreadId": "string",      "provider": "string",      "participantName": "string",      "participantExternalId": "string",      "lastMessageAt": "string",      "lastMessagePreview": "string",      "unread": true,      "accountId": "string",      "readOnly": true    }  ]}
POST
/messaging/channels/connect

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
entityId?string
externalThreadId*string
accountId*string
provider*string
participantName?string

Response Body

Channel created, upgraded, or already exists

application/json
  1. response
channelId*string
Example Request
curl -X POST 'https://pod.example.com/api/hub/messaging/channels/connect' \  -H 'Content-Type: application/json' \  -d '{  "externalThreadId": "string",  "accountId": "string",  "provider": "string"}'
Example Response
{  "channelId": "string"}
DELETE
/messaging/channels/{channelId}

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

channelId*string

Response Body

Channel unlinked

application/json
  1. response
success*boolean
Example Request
curl -X DELETE 'https://pod.example.com/api/hub/messaging/channels/string'
Example Response
{  "success": true}

Clear unread flag for a linked channel

POST
/messaging/channels/{channelId}/mark-read

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

channelId*string

Response Body

Marked as read

application/json
  1. response
success*boolean
Example Request
curl -X POST 'https://pod.example.com/api/hub/messaging/channels/string/mark-read'
Example Response
{  "success": true}

All unread conversations linked to entities

GET
/messaging/linked-unread

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Response Body

Unread linked conversations

application/json
  1. response
items*array<>
Example Request
curl -X GET 'https://pod.example.com/api/hub/messaging/linked-unread'
Example Response
{  "items": [    {      "entityId": "string",      "channelId": "string",      "externalThreadId": "string",      "provider": "string",      "participantName": "string",      "lastMessagePreview": "string",      "lastMessageAt": "string"    }  ]}

Get messages in a conversation thread

GET
/messaging/conversations/{threadId}/messages

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

threadId*string

Query Parameters

accountId*string

Response Body

Messages

application/json
  1. response
[index: integer]?
Example Request
curl -X GET 'https://pod.example.com/api/hub/messaging/conversations/string/messages?accountId=string'
Example Response
[  {    "externalMessageId": "string",    "threadId": "string",    "senderName": "string",    "body": "string",    "sentAt": "string",    "direction": "inbound",    "attachments": [      {        "name": "string",        "url": "string"      }    ]  }]

Import a conversation thread into the pod as a governed proposal

POST
/messaging/conversations/{threadId}/import

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

threadId*string

Request Body

application/json
  1. body
accountId*string
workspaceId?string
sessionId?string

Response Body

Import proposal created (or no messages to import)

application/json
  1. response
proposalId*string|null
recordCount*number
itemCount*number
gated?string
Value in"denied""deferred"
Example Request
curl -X POST 'https://pod.example.com/api/hub/messaging/conversations/string/import' \  -H 'Content-Type: application/json' \  -d '{  "accountId": "string"}'
Example Response
{  "proposalId": "string",  "recordCount": 0,  "itemCount": 0,  "gated": "denied"}

Send a message in a conversation thread

POST
/messaging/conversations/{threadId}/send

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

threadId*string

Request Body

application/json
  1. body
accountId*string
body*string

Response Body

Message sent

application/json
  1. response
success*boolean
Example Request
curl -X POST 'https://pod.example.com/api/hub/messaging/conversations/string/send' \  -H 'Content-Type: application/json' \  -d '{  "accountId": "string",  "body": "string"}'
Example Response
{  "success": true}

List all external channels (DB-backed inbox)

GET
/messaging/channels

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Query Parameters

provider?string
unreadOnly?string
Value in"true""false"

Response Body

External channels list

application/json
  1. response
channels*array<>
Example Request
curl -X GET 'https://pod.example.com/api/hub/messaging/channels'
Example Response
{  "channels": [    {      "channelId": "string",      "provider": "string",      "threadId": "string",      "title": "string",      "participantName": "string",      "lastMessageAt": "string",      "lastMessagePreview": "string",      "unread": true,      "entityId": "string",      "messageCount": 0    }  ]}

Memory

The Memory operations of the Hub REST API (7 operations).

Notifications

The Notifications operations of the Hub REST API (1 operation).