OpenAPI

OpenAPI is a specification for describing REST APIs. Using OpenAPI specification 2.0, you can create OpenAPI documents for the Business Messages and Business Communications APIs to describe their structure.

This allows you to do the following:

  • Create client libraries in your preferred language
  • Create server stubs
  • Use API management tools

Basic structure of an OpenAPI document

An OpenAPI document describes the surface of a REST API. The document defines the name and description of the API, the individual endpoints (paths) in the API, how the callers are authenticated, and more.

Click below to see an example of this basic structure.

JSON

    {
      "swagger": "2.0",
      "host": "businessmessages.googleapis.com",
      "info": {
        "title": "Business Messages API",
        "description": "",
        "version": "v1"
      },
      "paths": {
        "/v1/conversations/{conversationsId}/messages": {
          "post": {
            "description": "Sends a message from an agent to a user.",
            "parameters": [
              {
                "description": "Part of `parent`. Required. The conversation that contains the message. Resolves to \"conversations/{conversationId}\".",
                "type": "string",
                "in": "path",
                "required": true,
                "name": "conversationsId"
              },
              {
                "description": "Optional. A flag to send the specified fallback text instead of other message content.",
                "name": "forceFallback",
                "type": "boolean",
                "in": "query"
              },
              {
                "name": "message",
                "schema": {
                  "$ref": "#/definitions/BusinessMessagesMessage"
                },
                "in": "body",
                "description": "Required. The content of a message."
              }
            ],
            "tags": [
              "businessmessages"
            ],
            "operationId": "CreateMessage",
            "responses": {
              "default": {
                "schema": {
                  "$ref": "#/definitions/BusinessMessagesMessage"
                },
                "description": "Successful operation"
              }
            }
          }
        }
      }
    }

To learn more about the structure of an OpenAPI document, see the Swagger website.

How to access the OpenAPI documents

To access the OpenAPI documents, you must have an API key from a Google Cloud Platform (GCP) project with the Business Messages and Business Communications APIs enabled.

Follow the sections below to

  • create a GCP project
  • create an API key
  • enable the Business Messages API and Business Communications API

With these steps completed, you can access the OpenAPI documents.

Create a GCP project

If you already have a GCP project, you can use it to create an API key.

To create a new GCP project, do the following:

  1. Navigate to the Manage resources page in the GCP console.
  2. In the Select organization drop-down list at the top of the page, select the organization that you want to create the project for. If you are a free-trial user, skip this step.
  3. Click Create Project.
  4. In the New Project window, enter a project name and select a billing account as applicable. A project name can contain only letters, numbers, single quotes, hyphens, spaces, or exclamation points, and must be between 4 and 30 characters.

  5. For Location, enter the parent organization or folder for the new project.

  6. Click Create.

Create an API key

  1. Navigate to the Credentials page in the GCP console.

  2. Click Create credentials, then select API key.

    The API key created dialog box displays your newly created key. Copy your key and keep it secure. To learn more about API keys, see the API key documentation.

Enable the Business Communications API and Business Messages API

To enable these APIs in your GCP project, do the following:

  1. Go to the APIs & Services page in the GCP console.
  2. In the Select project drop-down list, select the project you want to enable the APIs for.
  3. Click Enable APIs and Services.
  4. In the Search for APIs and Services field, enter Business Messages.
  5. Select Business Messages API.
  6. Click Enable.
  7. Click Enable APIs and Services.
  8. In the Search for APIs and Services field, enter Business Communications.
  9. Select Business Communications API.
  10. Click Enable.

Now your API key has permissions to access the OpenAPI documents for the Business Messages and Business Communications APIs.

Access the OpenAPI documents

Run this command to access the OpenAPI document for the Business Messages API: 

curl "https://businessmessages.googleapis.com/$discovery/swagger2?version=v1&key=API_KEY"

Run this command to access the OpenAPI document for the Business Communications API: 

curl "https://businesscommunications.googleapis.com/$discovery/swagger2?version=v1&key=API_KEY"

Replace the API_KEY with your API key.