Connect API overview

The Connect API lets external systems manage contacts and send and read messages on behalf of a channel. The authenticated channel is the actor for every request, and all resources are scoped to the workspace identified by the request hostname.

Use the Connect API to:

• create, find, and update contacts;
• list contacts, channels, and channel templates;
• retrieve channel messages;
• send text and template messages, including encrypted messages; and
• close or reopen conversations.

All endpoints are rooted at /api/connect. Create a channel API key from Channel → Settings → API Key, then send it as a bearer token. See Authentication before making your first request.

Update contact information

Use PATCH /api/connect/contacts/{contact} to update an existing contact’s name, email, or phone. Replace {contact} with the UUID returned as id when you list, create, or find a contact. A valid Connect token can update any non-deleted contact in its workspace, even when the contact is not linked to the authenticated channel.

Send at least one supported field. Omitted fields stay unchanged:

PATCH /api/connect/contacts/d20f3c70-0269-4ff9-9fd2-08f592f68f10
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json
{
  "name": "Ada Okafor",
  "email": "ada@acme.com",
  "phone": "+2348031234567"
}

Strings are trimmed before validation. To clear an email or phone, send null or a blank string. When either contact method is supplied, the contact must retain at least one email or phone after the update. For example, this replaces the phone with an email in one request:

{
  "email": "ada@acme.com",
  "phone": null
}

Name-only updates are also allowed for legacy contacts that have neither an email nor a phone. Sending the contact’s current email or phone is allowed. Unsupported fields are ignored; this endpoint cannot change status, assignments, channel links, or metadata.

A successful request returns 200 with the updated contact under data.contact. The response uses phoneNumber for the phone field, while the request uses phone.

Invalid fields, duplicate contact methods, an empty or unsupported-only body, or clearing the last contact method return 422 with field messages under errors. Validation failures apply no changes. A malformed, missing, deleted, or other-workspace contact UUID returns 404. Unexpected update failures return 500 with {"status":"error","message":"Internal server error"} and roll back the changes.

Both channel and connection bearer tokens are supported. When a connection token is linked to multiple active channels, include X-Channel-Uuid with the target channel UUID. Missing, invalid, expired, or unavailable credentials return 401.

Recipient and attribution semantics

Message requests accept three recipient forms, resolved in this order:

1. to — a contact UUID, including a group contact, or an object containing contact details;
2. contact — an object containing contact details; or
3. sender — the legacy recipient object, used when neither to nor contact is present.

Use from to attribute a message to a Zorvia user or an external actor. When omitted, the authenticated channel is recorded as the sender.

Groups are represented as contacts. Retrieve the group from the contacts endpoint, then use its contact UUID in to to send a message directly to the group.

Send without reopening a conversation

Set silent to true when sending a message to an existing closed conversation and you want it to remain closed. The message is delivered and recorded on that conversation without creating a reopen state change. Omit silent, or set it to false, to use the normal conversation behavior.

JSON requests

Send Content-Type: application/json and Accept: application/json with request bodies. Collection endpoints support pagination and return pagination metadata alongside their data.