API Reference

Generate (asynchronous)

POST/cs/v1/content_creation/conversations/enqueue

Enqueue a conversation to be processed asynchronously

Open interactive API explorer ↗ · Download OpenAPI

Authentication

bearerAuth

Bearer authentication header of the form Bearer <token>, where <token> is an access key.

Example: Authorization: Bearer sk-proj-XXXXXXXXX

Type: bearer

Request body (required)

#application/json

Represents a request to enqueue a conversation

Type: object

#userProfileId stringrequired

A user profile ID; this will represent the profile that will receive the generated reply.

Type: string

#personaProfileId stringrequired

A persona profile ID; this will represent the profile that our operator will impersonate.

Type: string

#language stringrequired

The language used to generate the reply.

Type: string

Allowed values: "EN", "EN_GB", "FR", "FR_BE", "RO", "NL", "ES", "DE", "DE_CH", "DE_AT", "IT", "ES_LATAM", "BG", "HE", "JA", "NL_BE", "EN_AU", "PT_PT", "PT_BR", "SV_SE", "DA_DK", "FI_FI", "PL_PL", "LT_LT", "NB_NO", "NN_NO", "SL_SI", "HU", "HU_HU", "CS_CZ", "EL_GR", "EL_GR_LATIN", "EL_GR_GREEK", "HR_HR", "TR_TR", "EN_IE", "AF_ZA", "ZU_ZA", "LV_LV", "SK_SK", "GA_IE", "SR_RS", "ET_EE", "EN_CA", "FR_CA", "RU_RU", "UA_UA", "HI_IN", "HI_IN_LATIN", "KO_KR", "MS_MY", "MT_MT", "AR", "ZH_CN", "ZH_TW", "ZH_HK"

#additionalLanguages array

A list of additional languages that can be used to generate the reply. Currently, we support only one additional language.

Type: arrayminItems: 0 maxItems: 1

#Array items

Type: string

#userProfileVersion string,null

Specify the current user profile version. If it differs from the stored version, it will trigger a profile data refresh.

Type: string | null

#personaProfileVersion string,null

Specify the current persona profile version. If it differs from the stored version, it will trigger a profile data refresh.

Type: string | null

#tags object,null

A map of tags to associate with the generated answer. You can use any key-value pair to store additional information along with your request. You can use this to store arbitrary metadata, for events tracking or statistics.

Type: object | null

#Additional properties

Type: string

#testMode boolean,null

Specify whether the conversation should be processed in test mode. In test mode, you may receive a dummy answer at no charge instead of a generated one.

Not every request honours it today: some are answered by the AI and billed as usual. Do not rely on test mode to avoid charges.

Type: boolean | null

#replyParameters object,null

A set of parameters that allow you to customize the reply you receive from us, enabling greater flexibility and control over the response format, content, and behavior.

Type: object | null

#chatModel string

Allows you to set the AI chat model to use for generating the reply. If the field is omitted the request runs on chat-2-smart, which is also what default resolves to. An explicit null, an empty string or an unknown name is rejected with 400 Bad Request. Names are case-sensitive. 🚨🚨🚨 IMPORTANT NOTE: the default model is subject to change at any time, if you want to stick with a specific model make sure to provide it explicitly.

chat-latest-smart and chat-latest-pro always resolve to the latest released version of that tier, so a new version is picked up with no change on your side. Use a pinned name (chat-2.2-smart, chat-2-pro, …) to stay on one version for good.

chat-2-auto, chat-2.1-auto and chat-2.2-auto pick the tier for you on every request: a conversation of up to 30 messages runs on the Smart tier of that version, a longer one on the Pro tier. The message count only grows, so once past 30 the conversation stays on Pro for as long as you keep sending the -auto model. Long-term memory covers what is said from the first Pro reply on, not the messages before it, and its first memories are written about 20 messages later. The switch is invisible to the end user, and each reply is billed at the tier that produced it.

dating-smart-1 and dating-pro-1, the names of the retired Chat 1, are still accepted: they run chat-2-smart and chat-2-pro.

Type: stringdefault: "chat-2-smart"

Allowed values: "chat-latest-smart", "chat-latest-pro", "chat-2-smart", "chat-2-pro", "chat-2.1-smart", "chat-2.1-pro", "chat-2.2-smart", "chat-2.2-pro", "chat-2-auto", "chat-2.1-auto", "chat-2.2-auto"

#bufferSeconds integer

Allows you to set the AI buffer time (in seconds). This delay enables the AI to wait before generating a response, allowing it to accumulate more messages. If not specified, defaults to 5 seconds.

Type: integerformat: "int32" default: "5" minimum: 0 maximum: 180

#maxProcessingTimeSeconds integer

How long (in seconds) a request may wait in our queue before it is dropped. When it is exceeded, no answer is produced and you receive a conversation.dropped webhook event. It is not a limit on generation itself: a reply already being written is not interrupted, and the limit is not applied to every request. If not specified, defaults to 300 seconds.

Type: integerformat: "int32" default: "300"

#enableSexualTextContent boolean

Allows our chat models to generate sexual text content. Set it to false to cap the conversation at flirting: when the user turns it sexual, the reply stays flirty, whatever sexualDrive says. Casual and flirty conversations are not affected, and neither is an EROTIC icebreaker you ask for, which is still sent as written. If not specified, defaults to true.

Type: booleandefault: true

#fixedResponseLength boolean

Keeps the reply length exactly at messageLength. Without it, about one reply in five is made one step shorter or longer than the requested messageLength, so replies don't all look alike. It has no effect on sentenceLength. If not specified, defaults to false.

Type: booleandefault: false

#sentenceLength string,null

Allow you to specify the length of the sentences composing the response: SHORT (short and snappy), REGULAR (a natural rhythm) or LONG (longer, more elaborate sentences). On Chat 2, priority is this request value, then the persona's sentence length, then the project's maximumSentenceLength, then SHORT.

Type: string | nulldefault: null

Allowed values: "SHORT", "REGULAR", "LONG"

#messageLength string,null

Allow you to specify the length of the response, in sentences: SHORT (1 sentence), REGULAR (1 or 2), LONG (up to 3) or VERY_LONG (up to 4). On Chat 2, priority is this request value, then the persona's message length, then the project's maximumMessageLength, then REGULAR. See fixedResponseLength to stop the occasional one-step variation.

Type: string | nulldefault: null

Allowed values: "SHORT", "REGULAR", "LONG", "VERY_LONG"

#personaPersonality string,null

Allow you to override the personality given to the persona

Type: string | nulldefault: null

Allowed values: "SUPPORTIVE", "TEASING", "CONFIDENT", "GEEKY", "POETIC", "HIGH_ENERGY", "INTELLECTUAL", "ROMANTIC", "SARCASTIC", "POSSESSIVE", "NATURAL", "APPRECIATIVE", "PASSIONATE"

#generatePersonality boolean,null

Automatically generate the personality of the persona profile (SoulEngine). This will incurs an additional cost to the reply.

Type: boolean | nulldefault: null

#referencePersonaProfileId string,null

The persona profile ID under which the persona's personality (SoulEngine) is read and written, instead of personaProfileId.

Use it when several of your persona profile IDs describe the same persona — typically when you derive one profile ID per user (<personaProfileId>-<userProfileId>) to keep user-specific profile data. Point them all at the same referencePersonaProfileId and they share a single personality: it is generated (and billed) once for the reference ID, then reused by every profile referring to it, instead of once per derived profile.

Only the personality lookup and storage are affected. The reply is still generated from the profile data of personaProfileId, and this ID does not need to exist as a profile on its own — nothing is ever fetched for it.

If omitted (default), the personality is read and written under personaProfileId, as before.

Type: string | nulldefault: null minLength: 1 maxLength: 64

#shareablePictures array

A list of shareable picture objects that the persona is allowed to send when the user requests an image. Picture sharing is supported on every Chat 2 model: chat-2-*, chat-2.1-* and chat-2.2-* in their -smart, -pro and -auto forms, and chat-latest-*.

Type: array

#Array items

Type: object

#id stringrequired

Your identifier for this picture. Keep it stable across requests: we use it to remember which pictures have already been shared in the conversation, so a changing id makes the persona offer the same picture again.

Type: stringminLength: 1 maxLength: 128

#url stringrequired

URL we fetch the picture from. Maximum 512 characters. HTTPS is strongly recommended.

Type: stringminLength: 1 maxLength: 512

#caption string

A custom caption of the picture, this can be used to override the default caption generated by our AI.

Type: stringminLength: 1 maxLength: 100

#shareableVideos array

A list of shareable video objects that the persona is allowed to send when the user requests a video. A reply carries at most one medium: either a picture or a video, never both. Video sharing is supported on every Chat 2 model: chat-2-*, chat-2.1-* and chat-2.2-* in their -smart, -pro and -auto forms, and chat-latest-*.

Type: array

#Array items

Type: object

#id stringrequired

Your identifier for this video. Keep it stable across requests: we use it to remember which videos have already been shared in the conversation, so a changing id makes the persona offer the same video again.

Type: stringminLength: 1 maxLength: 128

#url stringrequired

URL we fetch the video from. Maximum 512 characters. HTTPS is strongly recommended.

Type: stringminLength: 1 maxLength: 512

#caption string

A custom caption of the video, this can be used to override the default caption generated by our AI.

Type: stringminLength: 1 maxLength: 100

#emojis string

Allows our operator/chat models to add emojis to the reply.

Emoji Frequency	Description
`FREQUENT`	50% at least 1 and maybe 1 more emoji if appropriate / 50% 1 if appropriate
`SOMETIMES`	75% 1 if appropriate / 25% no emoji
`RARELY`	75% no emoji / 25% 1 if appropriate
`NEVER`	100% no emoji

Type: string

Allowed values: "FREQUENT", "SOMETIMES", "RARELY", "NEVER"

#fluencyDegradation string,null

Allows our chat model to degrade the text content generation quality to improve human-like response. Defaults to NONE or LOW randomly (50/50).

Type: string | nulldefault: null

Allowed values: "LOW", "MEDIUM", "HIGH", "NONE"

#multipleMessagesPerReply boolean,null

Allows our AI to split a long response into multiple shorter messages. If not specified, defaults to false. This provides a more natural conversation flow by breaking down lengthy responses. Note that every message sent has its own answer.created event.

Type: boolean | nulldefault: false

#multipleMessagesPerReplyFrequency string,null

Changes the chances of replying with several messages. Ignored unless multiple messages per reply are enabled — either with multipleMessagesPerReply on this request, or in your project settings.

Type: string | nulldefault: null

Allowed values: "VERY_FREQUENT", "FREQUENT", "OCCASIONAL", "RARE"

#questionFrequency number

Deprecated — use questionFrequencyRate instead. Still honored on Chat 2 models, unchanged, and still defaults to 0.75. No removal is planned: it is the only question control on every model before chat-2.2, and those models are frozen. Nothing to change on your side, today or on a deadline.

A number from 0 to 1.

On every model before chat-2.2 — chat-2-* and chat-2.1-* — this is the only question control there is, and it behaves exactly as it always has, which is weaker than its name suggests: a value below 1 removes an encouragement rather than forbidding anything, so 0 still leaves the Persona free to ask. That behaviour is frozen on those models on purpose. Pinning a version is what keeps a prompt from changing underneath you, and questionFrequencyRate is ignored there — with one exception: the CHANGE_TOPIC engage, which did not exist before, reads questionFrequencyRate (else this number) on every chat-2 model to decide whether the new subject ends on a question, as one ask-or-don't draw per reply, the same way chat-2.2 reads it.

On chat-2.2 it is read as the same per-reply chance questionFrequencyRate expresses in named steps, so 0.5 here and MEDIUM there do the same thing, and a request that carries both follows the rate. Move to chat-2.2-smart / chat-2.2-pro (or chat-latest-smart / chat-latest-pro) to get the parameter its name describes.

The reason it is being retired is that the number promised a precision the mechanism never had: under it is a single decision per reply — ask, or do not ask — not a dial on how question-like a reply is. 0.37 and 0.4 were never two different things.

Type: numberformat: "double" minimum: 0 maximum: 1 deprecated: true

#questionFrequencyRate string,null

How often the Persona is asked to put a question to the User.

Value	Meaning
`NONE`	The Persona is told not to ask a question.
`LOW`	Roughly one reply in four asks.
`MEDIUM`	Roughly one reply in two asks.
`HIGH`	Roughly four replies in five ask.
`FULL`	The Persona is asked to put a question to the User.

The steps in between are a per-reply coin toss, not a softening: on a reply the toss does not select, the Persona is told not to ask, the same way it is at NONE. So LOW is not "asks a little in every reply" — it is "asks fully in about a quarter of them, and not at all in the rest".

The control is best effort. It shapes the instruction the Persona is given, not the text it produces, so the share of replies that end up containing a question tracks the value closely without matching it exactly — that is inherent to AI-generated replies.

Where it applies. Casual and flirty conversations, and the CHANGE_TOPIC engage, where it decides whether the new subject ends on a question. It has no effect on sexual or hostile conversations, nor on icebreakers, nudges, revives and late replies, all of which follow their own instructions.

Which models. chat-2.2-smart, chat-2.2-pro, chat-2.2-auto, and chat-latest-smart / chat-latest-pro, which resolve to them. Sending it to an earlier model has no effect; those read the deprecated questionFrequency with the behaviour they shipped with. The one exception is CHANGE_TOPIC, which reads it on every chat-2 model.

If omitted, the deprecated questionFrequency applies, which defaults to 0.75.

Type: string | nulldefault: null

Allowed values: "NONE", "LOW", "MEDIUM", "HIGH", "FULL"

#replyTypingDelay string

Introduces a delay between the answer.processing and answer.created events to simulate human-like typing behavior. This can enhance user experience by making responses feel more natural. See the Notify Your End Users use case for implementation example.

Type: stringdefault: "INSTANT"

Allowed values: "INSTANT", "FAST", "NORMAL"

#meetingPolicy string,null

Controls how the Persona handles in-person meeting requests from the user.

Value	Description
`DEFAULT_MODE`	(default when null) Warm refusal using a plausible personal excuse. Uses the stored long-term memory excuse if one is already present.
`DEFERRED_MEETING`	Expresses genuine desire to meet first, then softly refuses with a personal excuse, and ends on a hopeful note.
`RAINCHECK`	Declines with a specific, time-bound excuse and explicitly signals that meeting will happen later. Re-engages by showing interest in the user.
`CHAT_ONLY`	Firm but warm redirect back to the conversation. No implied future possibility of meeting. No personal-life excuses.
`EAGER_TO_MEET`	Always accepts meeting requests with immediate enthusiasm, treating the meeting as real and imminent. Pure fantasy — never refuses, defers, or breaks the illusion. Excluded from the meeting check below.

In every mode except EAGER_TO_MEET, a meeting check reads the Persona's replies. When one leaves a real-life meeting standing, her next reply takes it back; five in a row stop the conversation with IRL_MEETING_ACCEPTED and a progressive ban. The check has no option of its own: only disableSafetyFeatures turns it off.

Type: string | nulldefault: null

Allowed values: "DEFAULT_MODE", "DEFERRED_MEETING", "RAINCHECK", "CHAT_ONLY", "EAGER_TO_MEET"

#fictionalDisclosure boolean

When enabled and the AI Suspicion guardrail is triggered, the persona will disclose that it is a fictitious profile instead of denying it. Requires the AI Suspicion guardrail to be on (guardrails.aiSuspicion, enabled by default) — with it off, this has no effect.

Type: boolean

#disableSafetyFeatures boolean

Allows you to disable the Core Guardian security features for our chat models. You will be responsible for ensuring the content is safe for all users. Every guardrail and the meeting check are turned off. The hostility ban (USER_HOSTILE) still applies: preventAggressiveTone is what turns it off.

Type: boolean

#guardrails object

Selects which Core Guardian guardrails run for this request. This object replaces your project's Core Guardian settings — it is not merged with them. Any guardrail you leave out falls back to the platform default, not to what you configured in the dashboard, so send the complete set whenever you use this parameter. Ignored when disableSafetyFeatures is true, which turns every guardrail off.

Type: object

#maliciousContent boolean

Enable/Disable Malicious Content guardrail

Type: booleandefault: false

#maliciousContentOptionSet object

Overrides answer and banDurations for the Malicious Content guardrail. Only applies when maliciousContent is true.

Type: object

#answer boolean

Whether the persona still sends a final message when this guardrail bans the user. Defaults to true.

Type: boolean

#banDurations array

Escalating ban durations for this guardrail, in seconds — up to 5 values. The first applies to the user's first offence, the next to the following one; the last value repeats for every further offence. Defaults to [7200, 43200, 86400, 172800, 3153600000] (2h, 12h, 24h, 48h, permanent), or [3153600000] for the Underage guardrail. A permanent ban is the sentinel 3153600000 (about a century). The dashboard takes these durations in hours and converts them for you.

Type: arrayminItems: 0 maxItems: 5

#Array items

Type: integerformat: "int64"

#aiSuspicion boolean

Enable/Disable AI Suspicion guardrail

Type: booleandefault: true

#aiSuspicionOptionSet object

Overrides answer and banDurations for the AI Suspicion guardrail. Only applies when aiSuspicion is true.

Type: object

#answer boolean

Whether the persona still sends a final message when this guardrail bans the user. Defaults to true.

Type: boolean

#banDurations array

Type: arrayminItems: 0 maxItems: 5

#Array items

Type: integerformat: "int64"

#underageDetection boolean

Enable/Disable Underage Detection guardrail

Type: booleandefault: true

#underageDetectionOptionSet object

Overrides answer and banDurations for the Underage Detection guardrail. Only applies when underageDetection is true.

Type: object

#answer boolean

Whether the persona still sends a final message when this guardrail bans the user. Defaults to true.

Type: boolean

#banDurations array

Type: arrayminItems: 0 maxItems: 5

#Array items

Type: integerformat: "int64"

#unknownLanguage boolean

Enable/Disable Unknown Language guardrail

Type: booleandefault: true

#unknownLanguageOptionSet object

Overrides answer and banDurations for the Unknown Language guardrail. Only applies when unknownLanguage is true.

Type: object

#answer boolean

Whether the persona still sends a final message when this guardrail bans the user. Defaults to true.

Type: boolean

#banDurations array

Type: arrayminItems: 0 maxItems: 5

#Array items

Type: integerformat: "int64"

#messageRepetition boolean

Enable/Disable Message Repetition guardrail

Type: booleandefault: true

#messageRepetitionOptionSet object

Overrides answer and banDurations for the Message Repetition guardrail. Only applies when messageRepetition is true.

Type: object

#answer boolean

Whether the persona still sends a final message when this guardrail bans the user. Defaults to true.

Type: boolean

#banDurations array

Type: arrayminItems: 0 maxItems: 5

#Array items

Type: integerformat: "int64"

#prohibitedIllegalContent boolean

[Deprecated: Is not used and will be removed in the future] Enables Prohibited Illegal Content guardrail

Type: booleandefault: false deprecated: true

#prohibitedIllegalContentOptionSet object

This guardrail is deprecated and will be removed in the future.

Type: objectdeprecated: true

#answer boolean

Whether the persona still sends a final message when this guardrail bans the user. Defaults to true.

Type: boolean

#banDurations array

Type: arrayminItems: 0 maxItems: 5

#Array items

Type: integerformat: "int64"

#dangerousDrugUse boolean

[Deprecated: Is not used and will be removed in the future] Enables Dangerous Drug Use guardrail

Type: booleandefault: false deprecated: true

#dangerousDrugUseOptionSet object

This guardrail is deprecated and will be removed in the future.

Type: objectdeprecated: true

#answer boolean

Whether the persona still sends a final message when this guardrail bans the user. Defaults to true.

Type: boolean

#banDurations array

Type: arrayminItems: 0 maxItems: 5

#Array items

Type: integerformat: "int64"

#preventAggressiveTone boolean

If set to true, the AI will avoid using an aggressive or confrontational tone, even when the user is being rude, insulting, or hostile. It will remain calm, polite, and non-reactive in all situations, and will not retaliate or escalate the conversation. It also turns off the hostility ban: with it on, a conversation is never stopped with USER_HOSTILE. If not specified, your project's Prevent Aggressive Tone setting applies, which is on for projects created in the dashboard.

Type: boolean

#serviceLoyalty boolean

If set to true, the Persona will never validate or agree with complaints about the platform, service, or pricing. Instead, the Persona will deflect warmly in character and occasionally express genuine appreciation for being on the platform. This prevents the Persona from reinforcing negative sentiment that could lead users to disengage.

Type: boolean

#personaProfileOverrides object

Allows you to override a subset of persona profile attributes for the current request

Type: object

#sexualDrive string

This parameter adjusts the Persona’s sexual appetite and likelihood to engage in sexting.

Value	Description
`NONE`	The Persona will never send sexually explicit replies.
`LOW`	The Persona will rarely initiate or respond to sexual topics, even if prompted.
`NORMAL`	The Persona may engage in sexting if the conversation naturally leads there.
`HIGH`	The Persona will respond positively and proactively to sexual cues from the User faster.
`VERY_HIGH`	The Persona will initiate or escalate sexting as soon as the User shows any sexual intent.
`ADAPTIVE`	The Persona follows the User's tone from the first reply and never goes further than the User's own latest messages.

ADAPTIVE is a reply setting only: it is accepted here and in the project configuration, never as a generated persona trait.

Type: string

Allowed values: "VERY_HIGH", "HIGH", "NORMAL", "LOW", "NONE", "ADAPTIVE"

#vision object

Enable vision features that allow the AI to interpret, analyze, and understand images.

An omitted field follows the project's capabilities: Pictures turns on the four picture analyses, Videos the two video analyses. An explicit value always wins over the project, false included.

Vision is supported on every Chat 2 model: chat-2-*, chat-2.1-* and chat-2.2-* in their -smart, -pro and -auto forms, and chat-latest-*.

Type: object

#userProfilePictureAnalysis boolean

Enable user profile's picture analysis.

Type: boolean

#personaProfilePictureAnalysis boolean

Enable persona profile's picture analysis.

Type: boolean

#sharedPicturesAnalysis boolean

Enable user's shared pictures analysis. The pictures are analysed on their own, but comparing them against the user's profile picture (so the persona can tell whether it is the same person) also requires userProfilePictureAnalysis.

Type: boolean

#sharedVideosAnalysis boolean

Enable user's shared videos analysis.

Type: boolean

#shareablePicturesAnalysis boolean

Enable persona's shareable pictures analysis, this will allows our chat model to understand each image it is sharing.

Type: boolean

#shareableVideosAnalysis boolean

Enable persona's shareable videos analysis, this will allows our chat model to understand each video it is sharing. Videos carrying a caption are never analyzed.

Type: boolean

#audio object

What the persona does with the sound a user sends.

Separate from vision because it is a separate sense. Like the analyses under vision, it is opt-in: an omitted field follows the project's Audio capability, which is off unless the project turns it on, and an explicit value always wins over the project.

No table of supported models here, unlike vision. A voice message is transcribed when the reply to it is composed, by a dedicated speech model, before the chat model writes — so every chat model can answer one. With analysis off, the recording is never played: the Persona is told the user sent a voice message she cannot play, and says so.

Type: object

#sharedAudiosAnalysis boolean

Enable the analysis of the voice messages the user sends. The voice messages waiting for a reply are transcribed when the reply is composed, and the transcript becomes the message text, so the persona can answer what was said.

Omitted, it follows the project's Audio capability. Off, the recording is never read: the message reaches the persona with no transcript and none of the spoken-language, delivery or tone metadata the conversation history would describe, and she is told she cannot play it rather than answering words nobody read to her.

Type: boolean

#pictureSharingMode string

Controls how willingly the persona shares photos. NORMAL (default): only shares when explicitly asked. EAGER: shares naturally when the conversation calls for it.

Type: string

Allowed values: "NORMAL", "EAGER"

#forcePictureSharing string

Force the persona to share a picture in this reply. The value "true" (case-insensitive, surrounding whitespace ignored) → force and auto-pick from shareablePictures. Any other value is treated as a picture URL to force (in shareablePictures, or arbitrary — analyzed on the fly). Null → no forcing; the persona decides naturally. chat-2 only.

Type: string

#forceVideoSharing string

Force the persona to share a video in this reply. The value "true" (case-insensitive, surrounding whitespace ignored) → force and auto-pick from shareableVideos. Any other value is treated as a video URL to force (in shareableVideos, or arbitrary — analyzed on the fly). Null → no forcing; the persona decides naturally. A reply carries at most one medium: when forcePictureSharing also resolves, the picture wins. chat-2 only.

Type: string

#action object

Available actions:

Action	Description
`PAUSE_CONVERSATION`	This feature requests the Persona to send a message indicating that they are temporarily pausing the conversation without specifying a timeline for resuming. This is useful if you disconnect your Personas or limit your Users' messages. Optionally, you can specify a pause duration to be respected on DumGum. During this period, our platform will not respond to any new User messages in the affected conversation.
`USER_PHOTO_REACTION`	Requests the Persona to send a message reacting to one of the User's photos. Provide a `userPhotoReaction` object with a `source` (`PROFILE_PICTURE` or `URL`). When `source` is `URL`, a `url` pointing to the photo is required; for `PROFILE_PICTURE` the User's profile picture is used and `url` is optional.
`ENGAGE`	Requests the Persona to send an engagement message. Provide an `engage` object with a `mode` (`AUTO`, `ICEBREAKER`, `NUDGE`, `REVIVE`, `LATE_REPLY` or `CHANGE_TOPIC`) and an optional `type` — the angle within that arc, same values as the top-level `engageType` parameter. This is the preferred form; the top-level `engage` and `engageType` parameters remain supported and take precedence over this action when sent on the same request.

Type: object

#type stringrequired

The type of the action.

Type: string

Allowed values: "PAUSE_CONVERSATION", "USER_PHOTO_REACTION", "ENGAGE"

#pauseConversation object

Optional pause conversation parameters.

Type: object

#duration integer

Optional duration of the pause in seconds (maximum 12 hours). By default, the conversation will not be paused on DumGum side.

Type: integerformat: "int32" minimum: 1 maximum: 43200

#userPhotoReaction object

Type: object

#source stringrequired

The source of the photo.

Type: string

Allowed values: "PROFILE_PICTURE", "URL"

#url string,null

The URL of the photo. Required when source is set to URL.

Type: string | nulldefault: null

#caption string,null

Optional caption describing the photo. When set (non-blank), it is used as the photo description instead of the automatic vision analysis.

Type: string | nulldefault: null

#engage object

Requests an engagement message. Carries the same two options as the legacy top-level engage and engageType reply parameters, which remain supported and take precedence over this action when sent.

Type: object

#mode string

The engagement arc: which kind of engagement message to write. Same values as the legacy engage reply parameter — which, when sent on the same request, takes precedence over this action.

Manages engagement messages in conversations. By default, engagement messages are disabled. Set to AUTO for context-based engagement type selection. Note: Using specific values instead of AUTO will force that engagement type regardless of context.

Value	Description
`AUTO`	Selects best engagement type based on context
`ICEBREAKER`	Sends an icebreaker message when starting a new conversation. Specify an angle (`engage.type` on the action, `engageType` on the legacy parameter) to force one.
`NUDGE`	Sends re-engagement message after inactivity
`REVIVE`	Sends messages to reactivate dormant conversations
`LATE_REPLY`	Answers a User message that was left waiting, opening by owning the delay. Unlike the three above — which all assume the User went quiet and look for a reason to reach out — this one is for conversations where the Persona owes a reply.
`CHANGE_TOPIC`	Moves a conversation that goes in circles to a fresh subject. The Persona answers any waiting User message briefly first, then brings up something new, without ever announcing the switch.

LATE_REPLY is never selected by AUTO; ask for it explicitly. It needs a User message actually awaiting a reply, and one that has been waiting at least 3 hours of the User's waking time — hours between 22:00 and 07:00 in their own timezone do not count, since a message sent at bedtime and answered at breakfast is not a message anyone was left waiting on. With nothing waiting, or below that, the engagement is skipped and the request produces an ordinary reply instead of an apology out of proportion to the gap. The delay the Persona refers to is still the real elapsed time. No angle applies to it today; one sent alongside falls back to AUTO as usual.

CHANGE_TOPIC is never selected by AUTO either; ask for it explicitly. When sent, the subject changes every time — it works whether the User's message is waiting or the Persona wrote last, and follows your question setting (questionFrequencyRate, else questionFrequency) for whether the new subject ends on a question. It falls back on its own where a topic change makes no sense: an empty conversation gets an ICEBREAKER, a conversation the Persona has never written in gets its ordinary first reply, and a sexual or hostile conversation gets an ordinary reply. Safety comes first: when one of your enabled guardrails flags the turn — a User who says they are underage, for instance — the engagement is skipped and the reply follows that guardrail's guidance. No angle applies to it. Available on the chat-2 models (2.0, 2.1, 2.2); any other model produces an ordinary reply.

Type: string

Allowed values: "AUTO", "ICEBREAKER", "NUDGE", "REVIVE", "LATE_REPLY", "CHANGE_TOPIC"

#type string

The angle within the arc. Same values as the legacy engageType reply parameter — which, when sent on the same request, takes precedence over this action.

Specifies the angle for an engagement message. Applies across engage modes (ICEBREAKER, NUDGE, REVIVE) per each type's applicability; no type applies to LATE_REPLY yet, nor to CHANGE_TOPIC. If a type is sent for an engage mode it is not valid for, it falls back to AUTO.

Type	Description
`AUTO`	Automatically selects the appropriate angle
`NO_PHOTO`	Message about user having no photos
`MISSING_DETAIL`	Message about incomplete profile details
`MUCH_YOUNGER`	Message addressing significant age difference (user younger)
`MUCH_OLDER`	Message addressing significant age difference (user older)
`NEARBY`	Message highlighting close proximity
`GENERIC`	General conversation starter
`USER_ONLINE`	Message acknowledging user is currently online
`USER_OFFLINE`	Message for offline users
`JUST_JOINED`	Welcome message for new users
`EROTIC`	The persona will initiate the conversation with a strongly erotic message (icebreakers only: accepted on `NUDGE` and `REVIVE`, where it has no effect)
`PHOTO_COMMENT`	The Persona will engage the conversation by commenting the User main picture
`HAPPY_BIRTHDAY`	Wish the User a happy birthday (valid on `ICEBREAKER`, `NUDGE`, and `REVIVE`)

Icebreaker-only types (NO_PHOTO, MISSING_DETAIL, MUCH_YOUNGER, MUCH_OLDER, NEARBY, GENERIC, USER_ONLINE, USER_OFFLINE, JUST_JOINED, PHOTO_COMMENT) require the arc to be AUTO or ICEBREAKER; if sent for an engage mode they are not valid for, they fall back to AUTO.

Two more silent fallbacks to AUTO to be aware of: when no arc is set the type is validated against ICEBREAKER, and PHOTO_COMMENT falls back to AUTO when the user profile has no main picture.

Type: string

Allowed values: "AUTO", "NO_PHOTO", "MISSING_DETAIL", "MUCH_YOUNGER", "MUCH_OLDER", "NEARBY", "GENERIC", "USER_ONLINE", "USER_OFFLINE", "JUST_JOINED", "PHOTO_COMMENT", "EROTIC", "HAPPY_BIRTHDAY"

#postProcessing object

Allow you to customize the post-processing of the generated content. This can be used to replace specific characters or remove certain elements from the generated text. Sending this object replaces your project's Language-specific formatting setting in full, for this request only — every rewrite you leave out is read as false, not as your project's value.

Type: object

#greekRewrite boolean

Used for Greek answer generations. Replace ";" by "?" and accentuated characters by their non-accentuated equivalents.

When you send postProcessing, a key you leave out is false: it is not read from your project. Omit the whole postProcessing object to use your project's Language-specific formatting setting, configurable from the dashboard.

Type: boolean

#russianRewrite boolean

Used for Russian answer generations. Remove quotation marks the model places around individual slang words or short informal expressions, while leaving genuine quoted sentences intact.

Type: boolean

#romanianRewrite boolean

Used for Romanian answer generations. Replace diacritical characters by their non-diacritical equivalents.

Type: boolean

#germanRewrite boolean

Used for German answer generations (including Austria and Switzerland). Remove apostrophes from the chat forms gehts, gibts, wenns, sichs and habs, preserving quotations and structured text.

Type: boolean

#arabicRewrite boolean

Used for Arabic answer generations. Remove short-vowel marks (harakat) and the tatweel stretching character.

Type: boolean

Illustrative example

{
  "userProfileId": "<string>",
  "personaProfileId": "<string>",
  "language": "EN",
  "additionalLanguages": [
    "EN"
  ],
  "userProfileVersion": "<string>",
  "personaProfileVersion": "<string>",
  "tags": "<string>",
  "testMode": "<string>",
  "replyParameters": {
    "chatModel": "chat-2-smart",
    "bufferSeconds": "5",
    "maxProcessingTimeSeconds": "300",
    "enableSexualTextContent": true,
    "fixedResponseLength": false,
    "sentenceLength": null,
    "messageLength": null,
    "personaPersonality": null,
    "generatePersonality": null,
    "referencePersonaProfileId": null,
    "shareablePictures": [
      {
        "id": "<string>",
        "url": "<string>",
        "caption": "<string>"
      }
    ],
    "shareableVideos": [
      {
        "id": "<string>",
        "url": "<string>",
        "caption": "<string>"
      }
    ],
    "emojis": "FREQUENT",
    "fluencyDegradation": null,
    "multipleMessagesPerReply": false,
    "multipleMessagesPerReplyFrequency": null,
    "questionFrequency": 0,
    "questionFrequencyRate": null,
    "replyTypingDelay": "INSTANT",
    "meetingPolicy": null,
    "fictionalDisclosure": false,
    "disableSafetyFeatures": false,
    "guardrails": {
      "maliciousContent": false,
      "maliciousContentOptionSet": {
        "answer": false,
        "banDurations": [
          0
        ]
      },
      "aiSuspicion": true,
      "aiSuspicionOptionSet": {
        "answer": false,
        "banDurations": [
          0
        ]
      },
      "underageDetection": true,
      "underageDetectionOptionSet": {
        "answer": false,
        "banDurations": [
          0
        ]
      },
      "unknownLanguage": true,
      "unknownLanguageOptionSet": {
        "answer": false,
        "banDurations": [
          0
        ]
      },
      "messageRepetition": true,
      "messageRepetitionOptionSet": {
        "answer": false,
        "banDurations": [
          0
        ]
      },
      "prohibitedIllegalContent": false,
      "prohibitedIllegalContentOptionSet": {
        "answer": false,
        "banDurations": [
          0
        ]
      },
      "dangerousDrugUse": false,
      "dangerousDrugUseOptionSet": {
        "answer": false,
        "banDurations": [
          0
        ]
      }
    },
    "preventAggressiveTone": false,
    "serviceLoyalty": false,
    "personaProfileOverrides": {
      "sexualDrive": "VERY_HIGH"
    },
    "vision": {
      "userProfilePictureAnalysis": false,
      "personaProfilePictureAnalysis": false,
      "sharedPicturesAnalysis": false,
      "sharedVideosAnalysis": false,
      "shareablePicturesAnalysis": false,
      "shareableVideosAnalysis": false
    },
    "audio": {
      "sharedAudiosAnalysis": false
    },
    "pictureSharingMode": "NORMAL",
    "forcePictureSharing": "<string>",
    "forceVideoSharing": "<string>",
    "action": {
      "type": "PAUSE_CONVERSATION",
      "pauseConversation": {
        "duration": 0
      },
      "userPhotoReaction": {
        "source": "PROFILE_PICTURE",
        "url": null,
        "caption": null
      },
      "engage": {
        "mode": "AUTO",
        "type": "AUTO"
      }
    },
    "postProcessing": {
      "greekRewrite": false,
      "russianRewrite": false,
      "romanianRewrite": false,
      "germanRewrite": false,
      "arabicRewrite": false
    }
  }
}

Responses

#204 Response

No Content