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

# Send an event

> Something that happened to a contact. It goes on the customer's timeline, and as a card in any chat with them from the last 24 hours. Send a `userId`, a `phone`, or both.



## OpenAPI

````yaml /openapi.yaml post /events
openapi: 3.1.0
info:
  title: Frictionless Context API
  version: '1.0'
  description: >-
    Send who your customers are and what just happened to them, so agents see it
    beside the chat.
servers:
  - url: https://api.usefrictionless.com/api/v1
security:
  - apiKey: []
tags:
  - name: Contacts
  - name: Events
paths:
  /events:
    post:
      tags:
        - Events
      summary: Send an event
      description: >-
        Something that happened to a contact. It goes on the customer's
        timeline, and as a card in any chat with them from the last 24 hours.
        Send a `userId`, a `phone`, or both.
      operationId: createEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - event
              properties:
                userId:
                  type: string
                  description: >-
                    Your own user ID. Saved even before they ever chat, and
                    creates the contact if needed.
                  example: user_42
                phone:
                  type: string
                  description: >-
                    For someone already chatting on WhatsApp. 7 to 15 digits
                    with the country code.
                  example: '+2348012345678'
                event:
                  type: string
                  maxLength: 120
                  example: Transfer failed
                properties:
                  type: object
                  description: >-
                    Up to 20. `amount` and `reference` get their own rows on the
                    card.
                  additionalProperties:
                    type:
                      - string
                      - number
                      - boolean
                  example:
                    amount: NGN 45,000
                    reference: TRX_0001
                    reason: Insufficient funds
                level:
                  type: string
                  enum:
                    - problem
                    - info
                  description: >-
                    "problem" puts the event at the top of the agent's panel in
                    red. Leave it out and words like failed, declined or
                    rejected in the name make it a problem.
                occurredAt:
                  type: string
                  format: date-time
                  example: '2026-10-15T09:30:00Z'
                  description: Defaults to now. Can't be in the future.
      responses:
        '201':
          description: Saved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 3f6c1b2e-8a4d-4c1e-9b7a-2d5e6f708192
                  event:
                    type: string
                    example: Transfer failed
                  level:
                    type: string
                    enum:
                      - problem
                      - info
                  occurredAt:
                    type: string
                    format: date-time
                    example: '2026-10-15T09:30:00Z'
                  postedToConversations:
                    type: integer
                    description: How many active chats received a card.
                    example: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PlanRequired'
        '404':
          description: >-
            `customer_not_found`: only a phone was sent, and nobody with that
            number has chatted yet. Send a userId too, and the event is kept for
            when they do.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    BadRequest:
      description: >-
        `invalid_request` or `invalid_user_id`: something is missing or the
        wrong shape.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: '`missing_key` or `invalid_key`: no API key, or one that was rotated.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PlanRequired:
      description: '`plan_required`: the Context API is on the Pro plan and above.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: '`rate_limited`: over 300 requests a minute. Wait and retry.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
              description: Says what to fix.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Your API key (`fk_live_…`) from Settings → Developers.

````

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