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

# Send an Event to Addy

> Tell Addy something happened for a customer, such as an order shipped or a payment received. Within 24 hours of the customer's last message Addy writes the update itself, using only the facts you send. Later, it sends the event's WhatsApp template.

Use events to keep customers updated from your own systems: an order shipped, a payment arrived, an appointment moved, a document is ready.

**Before you start:** set your events up in [**AI Agent → Events**](https://app.adsera.in/dashboard/ai-agent?tab=events). For each event you set:

* its key (`type`), such as `order_shipped`
* what it means and what Addy should tell the customer
* the facts it carries, such as `order_id` and `tracking_url`
* a WhatsApp template to use when the 24-hour window has closed

You can also send a `type` you haven't set up, as long as you add a `description` of what happened.

**What Addy does:**

| When | What is sent |
| - | - |
| Within 24 hours of the customer's last message | Addy writes the update in its own voice, using **only** the facts in `data`. The response has `via: "message"` and the text. |
| After 24 hours | The event's WhatsApp template, with its variables filled from `data` or the contact. The response has `via: "template"`. With no template set, nothing is sent and `reason` is `outside_24h_window`. |
| Within 24 hours, but your team has taken the chat | Nothing is sent (`reason: "a_person_is_handling_this_chat"`), so Addy never talks over your salesperson. Outside the 24 hours the template still goes out. |

```bash theme={null}
curl -X POST https://app.adsera.in/api/pub/addy/events \
  -H "x-api-key: YOUR_APP_ID" -H "x-api-secret: YOUR_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"phone": "919876543210", "type": "order_shipped", "data": {"order_id": "A-1042", "courier": "Delhivery", "tracking_url": "https://track.example.com/AWB123"}}'
```

Every event is listed with what happened under **AI Agent → Events → Recent events**. WhatsApp Pay payments and Cal.com bookings need no event: Addy already knows about them.


## OpenAPI

````yaml POST /api/pub/addy/events
openapi: 3.1.0
info:
  title: AdsEra REST API
  description: >-
    Welcome to the AdsEra REST API. Use our API to integrate powerful,
    multi-channel communication (Email and WhatsApp) directly into your
    applications. Automate transactional messages, trigger marketing campaigns,
    manage your audience, and track performance programmatically.
  contact:
    name: Shubham
    email: shubham@adsera.in
  version: 1.0.0
servers:
  - url: https://app.adsera.in
    description: Production Server
security:
  - AppIdAuth: []
    AppSecretAuth: []
paths:
  /api/pub/addy/events:
    post:
      tags:
        - AI Agent (Addy)
      summary: Send an Event to Addy
      description: >-
        Tell Addy something happened for a customer, such as an order shipped or
        a payment received. Within 24 hours of the customer's last message Addy
        writes the update itself, using only the facts you send. Later, it sends
        the event's WhatsApp template.
      operationId: addyEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddyEventRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/AddyEventResult'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrmError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Your plan has no API access, has expired, or doesn't include
            WhatsApp.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrmError'
        '404':
          description: Contact or WhatsApp number not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrmError'
components:
  schemas:
    AddyEventRequest:
      type: object
      required:
        - phone
        - type
      properties:
        phone:
          type: string
          example: '919876543210'
          description: The customer's phone with country code.
        type:
          type: string
          example: order_shipped
          description: >-
            The event's key, as set up in AdsEra → AI Agent → Events (for
            example order_shipped, payment_received).
        description:
          type: string
          example: The order was handed to the courier.
          description: >-
            What happened, in plain words. Needed for events you haven't set up
            in AdsEra.
        data:
          type: object
          additionalProperties: true
          example:
            order_id: A-1042
            courier: Delhivery
            tracking_url: https://track.example.com/AWB123
          description: >-
            The facts Addy may tell the customer. Addy only uses what you send
            here.
        whatsapp:
          type: string
          description: 'Optional: id of the WhatsApp number to send from.'
    AddyEventResult:
      type: object
      properties:
        delivered:
          type: boolean
        via:
          type: string
          enum:
            - message
            - template
          description: >-
            message: Addy wrote it (inside 24 hours of the customer's last
            message). template: the event's WhatsApp template was sent.
        text:
          type: string
          description: What was sent.
        reason:
          type: string
          description: >-
            Why it wasn't sent: outside_24h_window (no template set for the
            event), a_person_is_handling_this_chat, addy_off, addy_not_set_up,
            event_turned_off, contact_not_found, no_whatsapp_number,
            not_in_audience, out_of_credits, busy_try_again.
    CrmError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Contact not found
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          example: 500
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Internal Server Error!
  responses:
    Unauthorized:
      description: Unauthorized. The API keys are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: 401
            success: false
            error: 'Unauthorized: Please provide valid API credentials.'
  securitySchemes:
    AppIdAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your application's unique ID.
    AppSecretAuth:
      type: apiKey
      in: header
      name: x-api-secret
      description: Your application's secret key.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.