Add a visitor note

POST

/api/v1/visitors/{visitor_id}/notes

curl --request POST \
  --url https://api.inside.chat/api/v1/visitors/example/notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "text": "example" }'

• Hosted Gateway
• Local development

Required scopes: conversation_read, visitor_notes_write, message_content_read, contact_read_pii
Data access: message_content, pii, internal_notes
MCP tool: visitor_note_add
Note: Write
Note: Idempotency-Key required
Note: mapped native author

Add a visitor note using the newest persisted conversation, including non-AI conversations, with an enabled native author mapped to this exact website. Requires an unrestricted installation policy. Visitors without a stored conversation are unavailable. Results are retained for 24 hours. A permanent content-free tombstone prevents the same key from creating a new effect after result expiry. Reuse the same key and identical input when retrying. Changed input or policy/revisions conflict. Current policy is checked before result reuse. An unknown outcome returns 409 outcome_unknown; never retry with a new key automatically.

Authorizations

• installation_token
• oauth_client_credentials
  conversation_read visitor_notes_write message_content_read contact_read_pii

Parameters

Path Parameters

visitor_id

required

string

/^vis_[0-9]{1,20}_[1-9][0-9]{0,18}_[1-9][0-9]{0,18}$/

Query Parameters

website_id

string

/^web_[0-9]{1,20}_[1-9][0-9]{0,18}$/

Optional; if present must match the resource owner.

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 128 characters /^[!-~]+$/

A stable key for this intended effect. Reuse the same key and input for retries; never automatically replace it after an unknown outcome.

Request Body^required

Media typeapplication/json

object

text

required

Nonempty after trimming; maximum length is 4000 UTF-16 code units.

string

>= 1 characters <= 4000 characters

Example ^generated

{
  "text": "example"
}

Responses

200

Authorized result. Projection depends on current scopes and data policy.

Media typeapplication/json

The stored note, attributed to the mapped native operator.

object

data

required

object

success

required

visitor_id

required

string

/^vis_/

note

required

object

id

required

string

note_id

required

integer

text

required

string

title

required

Any of:

string

string

null

null

author

required

Any of:

string

The mapped native operator.

string

null

null

created_at

required

Any of:

string

ISO 8601 UTC.

string

null

null

Example

{
  "data": {
    "success": true
  }
}

Headers

X-Gateway-Operation-Id

string

/^op_[a-f0-9]{64}$/

Retained command receipt identifier when command reservation was acknowledged; use operation_get with the original credential and website. Not proof of native success or delivery.

400

Invalid, duplicate or unsupported request parameters.

401

Missing, expired or revoked installation credential.

404

Resource not found or not permitted by current authority.

409

Idempotency_conflict: the key has different input or authority revisions; operation_in_progress: the same command is pending; operation_conflict: native business state rejects the change; outcome_unknown: the native result is uncertain or no longer retained. Keep the same key and input for retries; never automatically create a new key or resubmit the effect.

Media typeapplication/problem+json

object

type

required

string

title

required

string

status

required

integer

Allowed value: 409

code

required

string

Allowed values: idempotency_conflict operation_in_progress operation_conflict outcome_unknown

request_id

required

string

Example

{
  "status": 409,
  "code": "idempotency_conflict"
}

Headers

X-Gateway-Operation-Id

string

/^op_[a-f0-9]{64}$/

Retained command receipt identifier when command reservation was acknowledged; use operation_get with the original credential and website. Not proof of native success or delivery.

422

The requested capability is not available for application installations.

429

Per-app quota exceeded.

Headers

Retry-After

integer

>= 1

503

Enrollment, native service or required authority is unavailable.