Guides

Automate Engagement

Engage lets a Persona send a message first, instead of waiting for the user. Use it to open a new chat, to follow up when someone goes quiet, or to answer a message that was left waiting. It is off by default: a Persona only reaches out when you ask it to.

You control it with two values:

the mode: the kind of message to send;
the angle (engageType): what the message opens on. Optional.

{
  "replyParameters": {
    "action": {
      "type": "ENGAGE",
      "engage": { "mode": "ICEBREAKER", "type": "PHOTO_COMMENT" }
    }
  }
}

The five modes

Mode	Use it when	What the Persona does
`AUTO`	You'd rather not decide	Picks the right mode from the conversation. Never picks `LATE_REPLY`.
`ICEBREAKER`	There is no conversation yet	Writes a first message based on the user's profile
`NUDGE`	The user went quiet recently	Follows up gently, on the same topic
`REVIVE`	The conversation died a while ago	Restarts it, on the old topic or a new one
`LATE_REPLY`	Your Persona left a message unanswered	Owns the delay, then answers what the user said

AUTO is the easy choice: no timing to track on your side. The other four force that mode, whatever the conversation looks like.

The angles (`engageType`)

The angle picks what the message opens on. Leave it out, or set AUTO, and the Persona chooses.

`engageType`	The message opens on	Works with
`AUTO`	Whatever fits best	Every mode
`GENERIC`	A simple, universal opener	`ICEBREAKER`, `AUTO`
`NO_PHOTO`	The user having no photo	`ICEBREAKER`, `AUTO`
`PHOTO_COMMENT`	The user's main profile picture	`ICEBREAKER`, `AUTO`
`MISSING_DETAIL`	A missing profile detail (age, interests…)	`ICEBREAKER`, `AUTO`
`MUCH_YOUNGER`	The user being much younger	`ICEBREAKER`, `AUTO`
`MUCH_OLDER`	The user being much older	`ICEBREAKER`, `AUTO`
`NEARBY`	The two of them being close by	`ICEBREAKER`, `AUTO`
`USER_ONLINE`	The user being online right now	`ICEBREAKER`, `AUTO`
`USER_OFFLINE`	The user being away	`ICEBREAKER`, `AUTO`
`JUST_JOINED`	The user having just signed up	`ICEBREAKER`, `AUTO`
`EROTIC`	A strongly erotic opener	`ICEBREAKER`, `NUDGE`, `REVIVE`, `AUTO`
`HAPPY_BIRTHDAY`	Birthday wishes	`ICEBREAKER`, `NUDGE`, `REVIVE`, `AUTO`

Only EROTIC and HAPPY_BIRTHDAY work outside icebreakers. No angle applies to LATE_REPLY.

Automatic behaviour to know about

An angle is never an error. When it doesn't apply, the Persona quietly falls back to AUTO and still sends the message:

The angle doesn't match the mode (for example NEARBY with NUDGE) → AUTO.
PHOTO_COMMENT but the user has no main picture → AUTO.
An angle sent with no mode at all → it is checked against ICEBREAKER.

LATE_REPLY has two conditions of its own:

A user message must actually be waiting for an answer.
It must have waited at least 3 hours of the user's waking time. Hours between 22:00 and 07:00 in the user's own timezone don't count. A message sent at bedtime and answered at breakfast kept nobody waiting.

If either condition fails, the engagement is skipped and the user simply gets an ordinary reply. The message is never dropped, and the Persona never apologises out of proportion to the delay. When it does run, the delay the Persona mentions is the real one.

Full parameter details are in the API reference.