> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatzy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Insert a nudge message into a conversation

Inserts a nudge message into an ongoing conversation.\
Nudge messages are designed to re-engage users by prompting them with a friendly reminder or question.

**Important:**\
Nudge messages that are sent while the AI Agent is generating a response will not be inserted into the conversation and will be ignored.

***

## Usage Scenarios

### 1. Using Chatzy's iframe as the UI

When you embed Chatzy's iframe URL inside your application or website, you **must send a `postMessage`** to the iframe to insert a nudge message.

Example:

```js theme={null}
const iframe = document.getElementById('chatzy-iframe');

const message = {
  type: '[ASSISTANT_NUDGE]',
  nudge_message: 'This is a test nudge sent into the iframe',
};

// Send to iframe
iframe.contentWindow.postMessage(JSON.stringify(message), '*');
```

* The iframe id will be `chatzy-iframe` if you are using the default embed code.
* If you assign a custom id to the iframe, replace "chatzy-iframe" with your own iframe element’s ID.
* The iframe URL can be embedded inside any app or website and the mechanism remains the same.

**Note:**
When a `postMessage` is received, Chatzy AI internally calls this `/insert_nudge_message` endpoint on your behalf. You don't need to call it directly in this case.

### 2. Using Your Own Custom UI

If you are not using Chatzy's iframe but have built your own UI for conversations, you can insert the nudge message directly into your interface as you see fit.

However, to keep Chatzy's backend conversation history in sync, you must call this endpoint immediately after inserting the nudge into your UI.

* `POST /insert_nudge_message`

* Request body:

```json theme={null}
{
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "nudge_message": "Hi, do you need any help?"
}
```

This ensures the nudge message is properly logged and will be reflected in Chatzy's systems.


## OpenAPI

````yaml post /insert_nudge_message
openapi: 3.0.0
info:
  title: Chatzy AI API
  version: 1.0.0
  description: >-
    Chatzy AI REST API for messaging, contact conversations, and agent
    interactions.
  contact:
    name: Chatzy
    url: https://chatzy.ai
    email: support@chatzy.ai
servers:
  - url: https://vevdoh3hve.execute-api.us-east-1.amazonaws.com/prod
    description: Production Server
security: []
tags:
  - name: Authentication
    description: Authentication to access the API
  - name: Contact Conversations
    description: Get contact conversations
  - name: Conversational AI Agent Interactions
    description: Interact with the conversational AI agent
  - name: Authorized iframe Access
    description: APIs for authorized iframe access
paths:
  /insert_nudge_message:
    post:
      tags:
        - Conversational AI Agent Interactions
      summary: Insert a nudge message into a conversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                conversation_id:
                  type: string
                  format: uuid
                  description: Conversation ID where the nudge message will be added
                  example: 550e8400-e29b-41d4-a716-446655440000
                nudge_message:
                  type: string
                  maxLength: 1000
                  description: Text content of the nudge message
                  example: Hi, do you need any help?
              required:
                - conversation_id
                - nudge_message
      responses:
        '200':
          description: Nudge message inserted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Nudge message inserted successfully

````