SimpleTexting Webhooks API

openapi: 3.2.0
info:
  title: SimpleTexting API Documentation Webhooks API
  description: '# Introduction



    Thousands of businesses rely on SimpleTexting to communicate with their audience via text message. With our API, developers can access many of our platform’s features and integrate them with other websites or applications. This document details the available SimpleTexting API functions and their parameters. For additional security, our API is by approval only. If you’d like access, sign up for a trial account and email [support@simpletexting.net](mailto:support@simpletexting.net) with details about your use case.


    **How it works**


    Our API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer). It uses standard HTTP response codes and authentication. Before you get started, there a few things to keep in mind:


    - When using the POST request, you must specify that `content-type` is `application/json`.



    - The format of responses for all requests is JSON, you can skip the `Accept` request header or set it to `application/json`.


    # Authentication


    Each time you make a request to our API, we use a bearer token in your header to authenticate your account. API requests without authentication will fail. Your API token can be found under [settings](https://app2.simpletexting.com/integrations/webhooks).<br><br>

    Please be sure to keep your bearer token secure. Don’t share it any public areas such as GitHub, client-side code, etc.


    <!-- ReDoc-Inject: <security-definitions> -->

    '
  termsOfService: https://simpletexting.com/terms/
  version: 2.0.0
servers:
- url: https://api-app2.simpletexting.com/v2
security:
- api_key: []
tags:
- name: Webhooks
  description: 'Use webhooks to communicate between the SimpleTexting platform and your server. Webhooks can be used to forward messages as well as provide info about unsubscribes and message delivery.


    SimpleTexting can trigger webhooks for new incoming messages, delivery reports, unsubscribes, and more. Now you can build scripts that interpret and respond to events that occur in your SimpleTexting account! To set the URLs for your webhooks, visit the Webhooks tab on the API section of [settings](https://app2.simpletexting.com/integrations/webhooks).'
paths:
  /api/webhooks/{webhookId}:
    put:
      tags:
      - Webhooks
      summary: Update a Webhook
      description: Update an existing webhook using its unique ID.
      operationId: updateWebhook
      parameters:
      - name: webhookId
        in: path
        description: Webhook ID in hexadecimal format
        required: true
        schema:
          type: string
        example: 507f1f77bcf86cd799439011
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
        required: true
      responses:
        '200':
          description: Success. Webhook was updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectIdDto'
        '404':
          description: Error. Webhook not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectIdDto'
    delete:
      tags:
      - Webhooks
      summary: Delete a Webhook
      description: 'Delete an existing Webhook by its unique ID.


        **Example:** Here we delete a Webhook whose ID is`507f1f77bcf86cd799439011`. You can use the [Get all Webhooks](#operation/getWebhooks) endpoint to retrieve message IDs for all of your Webhooks:


        `https://api-app2.simpletexting.com/v2/api/webhooks/507f1f77bcf86cd799439011`'
      operationId: deleteWebhook
      parameters:
      - name: webhookId
        in: path
        description: Webhook ID in hexadecimal format
        required: true
        schema:
          type: string
        example: 507f1f77bcf86cd799439011
      responses:
        '204':
          description: Success. Webhook was deleted.
  /api/webhooks:
    get:
      tags:
      - Webhooks
      summary: Get all Webhooks
      description: 'Retrieve all the webhooks that you''ve created.


        **Example:** Here we return all Webhooks from an account:


        `https://api-app2.simpletexting.com/v2/api/webhooks`'
      operationId: getWebhooks
      parameters:
      - name: page
        in: query
        description: An ordinal number of the page to return with the results of a request (with the webhooks of the given account). Please note that page numbering starts at zero (`0`)
        required: false
        schema:
          minimum: 0
          type: integer
          format: int32
          default: 0
        example: 5
      - name: size
        in: query
        description: The number of the returned webhooks to show per page
        required: false
        schema:
          maximum: 500
          type: integer
          format: int32
          default: 50
        example: 50
      responses:
        '200':
          description: Success. Returns page of webhooks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageViewWebhook'
    post:
      tags:
      - Webhooks
      summary: Create a Webhook
      description: Create a new webhook from scratch.
      operationId: createWebhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
        required: true
      responses:
        '201':
          description: Success. Webhook was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectIdDto'
        '400':
          description: Error. Invalid phone format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectIdDto'
components:
  schemas:
    WebhookRequest:
      required:
      - triggers
      - url
      type: object
      properties:
        url:
          type: string
          description: 'The URL for handling a POST request


            **Example:** `https://example.com`'
          example: https://example.com
        triggers:
          type: array
          description: "Trigger a webhook based on a specific platform event:\n\n  - **INCOMING_MESSAGE:** Trigger a webhook event based on an incoming message\n\n  - **OUTGOING_MESSAGE:** Trigger a webhook event based on an outgoing message\n\n  - **DELIVERY_REPORT:** Trigger a webhook when a delivery confirmation is received from a contact\n\n  - **NON_DELIVERED_REPORT:** Trigger a webhook when a failed delivery is reported from a contact\n\n  - **UNSUBSCRIBE_REPORT:** Trigger a webhook when a contact unsubscribes\n\n**Example:** `UNSUBSCRIBE_REPORT`"
          example:
          - INCOMING_MESSAGE
          items:
            type: string
            description: "Trigger a webhook based on a specific platform event:\n\n  - **INCOMING_MESSAGE:** Trigger a webhook event based on an incoming message\n\n  - **OUTGOING_MESSAGE:** Trigger a webhook event based on an outgoing message\n\n  - **DELIVERY_REPORT:** Trigger a webhook when a delivery confirmation is received from a contact\n\n  - **NON_DELIVERED_REPORT:** Trigger a webhook when a failed delivery is reported from a contact\n\n  - **UNSUBSCRIBE_REPORT:** Trigger a webhook when a contact unsubscribes\n\n**Example:** `UNSUBSCRIBE_REPORT`"
            example: '["INCOMING_MESSAGE"]'
            enum:
            - INCOMING_MESSAGE
            - OUTGOING_MESSAGE
            - DELIVERY_REPORT
            - NON_DELIVERED_REPORT
            - UNSUBSCRIBE_REPORT
        requestPerSecLimit:
          maximum: 25
          type: integer
          description: 'The maximum number of requests that can be sent within a second


            **Example:** `15`'
          format: int32
          example: 15
        accountPhone:
          type: string
          description: 'Optional: requests will come exclusively for the specified account phone number


            **Example:** `8881234567`'
          example: '8881234567'
        contactPhone:
          type: string
          description: 'Optional: requests will come exclusively for the specified contact''s phone number


            **Example:** `3051234567`'
          example: '3051234567'
    PageViewWebhook:
      type: object
      properties:
        content:
          type: array
          description: Page content and number of elements is restricted by page size.
          items:
            $ref: '#/components/schemas/Webhook'
        totalPages:
          type: integer
          description: The total number of pages. This is the number of elements divided by the page size.
          format: int32
        totalElements:
          type: integer
          description: Total number of elements.
          format: int64
      description: Page representation for search/fetch result
    Webhook:
      required:
      - triggers
      - url
      type: object
      properties:
        webhookId:
          type: string
          description: Webhook ID in hexadecimal format
          example: 507f191e810c19729de860ea
        url:
          type: string
          description: 'URL for handling POST request


            **Example:** `https://example.com`'
          example: https://example.com
        triggers:
          type: array
          description: 'Trigger a webhook on specific platform events


            **Example:** `INCOMING_MESSAGE`'
          example: INCOMING_MESSAGE
          items:
            type: string
            description: 'Trigger a webhook on specific platform events


              **Example:** `INCOMING_MESSAGE`'
            example: INCOMING_MESSAGE
            enum:
            - INCOMING_MESSAGE
            - OUTGOING_MESSAGE
            - DELIVERY_REPORT
            - NON_DELIVERED_REPORT
            - UNSUBSCRIBE_REPORT
        requestPerSecLimit:
          type: integer
          description: 'The maximum number of requests that can be sent within one second


            **Example:** `20`'
          format: int32
          example: 20
        accountPhone:
          type: string
          description: 'Optional: requests will come exclusively for the specified account phone number


            **Example:** `8881234567`'
          example: '8881234567'
        contactPhone:
          type: string
          description: 'Optional: requests will come exclusively for the specified contact phone number


            **Example:** `3051234567`'
          example: '3051234567'
      description: Page content and number of elements is restricted by page size.
    ObjectIdDto:
      type: object
      properties:
        id:
          type: string
          description: 'ID of item in hexadecimal format.


            **Example:** `507f191e810c19729de860ea`'
          example: 507f191e810c19729de860ea
      description: ID of created or modified object
  securitySchemes:
    api_key:
      type: apiKey
      description: 'Bearer authentication (also called token authentication) is an authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the `Authorization: Bearer <token>` header when making requests to protected resources. To understand more about bearer tokens, please take a look at the following [resource](https://swagger.io/docs/specification/authentication/bearer-authentication/).'
      name: Authorization
      in: header
x-tagGroups:
- name: CAMPAIGNS & MESSAGES
  tags:
  - Campaigns
  - Messages
  - Media Items
  - File Information
- name: Contacts
  tags:
  - Contacts
  - Contacts - Batch Operations
  - Contact Lists
  - Contact Segments
  - Custom Fields
- name: Webhook Services
  tags:
  - Webhooks
  - Webhook Reports