Skip to content
mondochat

Create or update a user

PUT
/v1/server/users/{external_id}
curl --request PUT \
  --url https://app.mondochat.io/v1/server/users/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Mondochat-App-Id: <Mondochat-App-Id>' \
  --data '{ "avatar": "https://example.test/alice.jpg", "lang": "en", "name": "Alice", "role": "member" }'

Creates the user with this external id or updates their profile, without opening a session. Server route: send the server secret as a bearer token with Mondochat-App-Id. tier must be a key of workspace.tiers; null clears it and leaving it out keeps the stored one.

Errors: 422 validation for an unknown role or tier or a reserved external id; 403 forbidden while a test app already has 50 users.

Guide: Users.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
external_id
required
External Id
string
/^[A-Za-z0-9._:@-]{1,128}$/

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
Profile

A user’s profile, as your server sets it.

object
avatar
Any of:
string
<= 2048 characters /^https://\S+$/
lang
Any of:
string
Allowed values: it en es fr
name
required
Name

Display name.

string
>= 1 characters <= 100 characters
perms
Any of:
Perms

Per-user overrides carried in the perms claim; a null field changes nothing.

object
block
Any of:
boolean
buy
Any of:
boolean
call
Any of:
boolean
message
Any of:
boolean
messages_per_minute
Any of:
integer
>= 1
messages_to_unanswered
Any of:
integer
new_conversations_per_day
Any of:
integer
offers
Any of:
boolean
photo_consent_required
Any of:
boolean
photos
Any of:
boolean
photos_per_day
Any of:
integer
require_vouch
Any of:
boolean
see_presence
Any of:
boolean
start_conversation
Any of:
boolean
voice_per_day
Any of:
integer
role
Any of:
string
/^[A-Za-z0-9_-]{1,32}$/
tier
Any of:
string
/^[A-Za-z0-9_-]{1,32}$/

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
User

A user of the app, as your server and the chat see them.

object
avatar
Any of:
string
external_id
required
External Id

The user’s id on your site, the sub claim.

string
id
required
Id

The user’s id in mondochat.

string format: uuid
kind
required
Kind

member for a user your server signed in, guest for an anonymous one.

string
Allowed values: member guest
name
required
Name

Display name.

string
role
required
Role

A role key from the app’s roles.

string

Example 

{
  "avatar": "https://example.test/alice.jpg",
  "external_id": "alice",
  "id": "0199d6a0-1000-7000-8000-000000000001",
  "kind": "member",
  "name": "Alice",
  "role": "member"
}

4XX

Section titled “4XX”

Problem

Media typeapplication/problem+json

An RFC 9457 problem: the body of every error answer.

object
code
required

The stable error code to branch on, such as policy_denied.

string
detail

What went wrong this time, when there is more to say.

string | null
errors

For validation, one entry per invalid field.

Array<object>

One invalid field.

object
loc

The path to the field.

array
msg

What is wrong with it.

string
instance

The path of the request.

string
reason

For policy_denied and limit_reached, the rule or limit that refused the request; for forbidden, a short cause such as you_blocked; for banned, temporary when the ban expires.

string
status
required

The HTTP status code.

integer
title
required

A short summary of the problem.

string
type
required

A URL that names the problem, https://app.mondochat.io/problems/<code>.

string

Example 

{
  "code": "policy_denied",
  "detail": null,
  "instance": "/v1/conversations/0199d6a0-2000-7000-8000-000000000001",
  "reason": "pins",
  "status": 403,
  "title": "Policy denied",
  "type": "https://app.mondochat.io/problems/policy_denied"
}