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, to answer a message that was left waiting, or to change the subject when a chat goes in circles. 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 six modes

AUTO is the easy choice: no timing to track on your side. The other five 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.

Only HAPPY_BIRTHDAY works outside icebreakers. EROTIC is accepted on NUDGE and REVIVE but changes nothing there: the message follows the mode's usual arc. No angle applies to LATE_REPLY or CHANGE_TOPIC.

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.

CHANGE_TOPIC changes the subject every time you send it, whether the user is waiting for an answer or the Persona wrote last. Where a new subject makes no sense, it falls back on its own:

• The conversation is empty → an ICEBREAKER.
• The Persona has never written in it → an ordinary first reply.
• The conversation is sexual or hostile → an ordinary reply.

Whether the new subject ends on a question follows your question setting (questionFrequencyRate, or questionFrequency if you still use it).

Full parameter details are in the API reference.