Hand-offs

Reply to a hand-off

Answer the customer. This is the only endpoint that sends something to one of your customers, so it behaves differently from the rest of the API.

Credential: user token · Role: owner, admin or responder (reply)

The reply leaves the building

It is not “add a message to a thread”. It goes out on the channel the conversation started on — back to WhatsApp, Messenger or Instagram, or by email from the connected mailbox — and is mirrored into the linked Slack thread and appended to the Zendesk or HubSpot ticket. If the customer is in the widget, it signals that a human has arrived.

Authorship comes from the token, never the body. The message is attributed to the token’s owner, and the name your customer sees is that teammate’s profile name. There is no way to reply as someone else, and the audit trail names who answered.

Text only, and attachments are refused rather than dropped. The body takes 1–10,000 characters. Sending attachments is a 400, not a silent omission — attaching a file needs an authenticated upload into your workspace’s own storage, so it stays a dashboard flow.

Side effects worth knowing

Replying also stamps the first-reply time, and auto-assigns the hand-off to you if nobody owns it yet.

It emits handoff.message.created — and, with resolve: true, handoff.status.changed. If you wire both an API reply path and a webhook consumer, you will receive your own reply back as an event. Dedupe on the event id.

POST

handoffs

{id}

curl --request POST \
  --url https://api.peeve.ai/v1/handoffs/{id}/reply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "body": "Both charges on 12 Aug were for the same invoice — I've refunded the duplicate."
}
EOF

{
  "object": "<string>",
  "data": {},
  "request_id": "<string>"
}

Authorizations

Authorization

string

header

required

A user token (pv_ut_…) as Authorization: Bearer pv_ut_…. X-Peeve-Key is accepted too. Never a query parameter — URLs end up in proxy logs and Referer headers.

The token carries its owner's live workspace role, re-read on every call.

Path Parameters

string<uuid>

required

Body

application/json

body

string

required

The reply text. Trimmed; must not be empty.

Required string length: 1 - 10000

resolve

boolean

default:false

Answer and close in one call. Default false, which leaves the hand-off waiting on the customer.

Response

The reply was sent.

object

string

required

The resource type, e.g. lead.

data

object

required

request_id

string

required

Echoed in the X-Request-Id header. Quote it to support.

⌘I

curl --request POST \
  --url https://api.peeve.ai/v1/handoffs/{id}/reply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "body": "Both charges on 12 Aug were for the same invoice — I've refunded the duplicate."
}
EOF

{
  "object": "<string>",
  "data": {},
  "request_id": "<string>"
}

Overview

Sessions

Contacts

Users

Leads

Meetings

Hand-offs

Analytics

Configuration

Webhooks

Ask

Reply to a hand-off

The reply leaves the building

Side effects worth knowing

Authorizations

Path Parameters

Body

Response