intercom / intercom-openapi

An OpenAPI description for Intercom's REST API

Intercom's REST API OpenAPI Description

This repository contains OpenAPI descriptions for Intercom's REST API. It covers API versions 2.7 and higher.

What is OpenAPI?

From the OpenAPI Specification:

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Contributing

Because this description is automatically generated from our internal codebase, we don't currently accept pull requests that directly modify the description. See CONTRIBUTING.md for more details.

If you've identified a mismatch between the Intercom API's behavior and these descriptions, or found an issue with the format of a schema, please open an issue.

intercom-openapi's Issues

Webhook Contact Objects inconsistent ti API Contact

The API documentation states that several of the callbacks contain a Contact object. However this object refuses to marshal because time fields are not represented as integers, as per the API contact object. Instead they are represented as ISO8601 timestamps. This requires manual creation of a second contact object in order to marshal a webhook response.

[Schema Inaccuracy] `sort` parameter is available but not documented.

Schema Inaccuracy

The searchConversations endpoint lacks documentation for the sort option, which is available but not mentioned. I'm trying to generate a Golang client.

Expected

I expect the documentation to include information about the sort functionality.

Reproduction Steps

Use the following cURL command with your Intercom API token:

curl -i -X POST \
  https://api.intercom.io/conversations/search \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.10' \
  -d '{
  "sort": {
    "field": "id",
    "order": "ascending"
  },
  "query": {
    // YOUR_QUERY_HERE
  }
}'

[Schema Inaccuracy] `last_closed_by_id` and `team_assignee_id` are not string type

Schema Inaccuracy

There seems to be a discrepancy in the documentation. The team_assignee_id and statistics.last_closed_by_id fields are described as having a string data type, but the API is returning them as numbers.

tickets/search API unable to retrieve tickets with a custom ticket_attribute set

tickets/search API unable to retrieve tickets with a custom ticket_attribute set

Hello

I am looking to use the tickets/search API to retrieve tickets with a particular ticket_attribute set.

This might already be possible but I am getting the syntax wrong, I can see on this page https://developers.intercom.com/docs/references/rest-api/api.intercom.io/Tickets/searchTickets/
it says you can use ticket_attribute.{id} as a field key but when I try this with a ticket attribute I am getting an error - field_not_found The request ticket attribute ID is not a valid integer response 400

Please advise on what I could be doing wrong here, thank you

Expected

import requests

url = https://api.intercom.io/tickets/search
 
payload = {
  "query": {

    "operator": "AND",

    "value": [

      {

        "field": "ticket_attribute.{my_ticket_attribute}",

        "operator": "=",

        "value": "Ready"

      },

      ]

   }

}


headers = {
  "Content-Type": "application/json",

  "Intercom-Version": "2.10",

  "Authorization": "Bearer <YOUR_TOKEN_HERE>"

}


response = requests.post(url, json=payload, headers=headers)


data = response.json()

print(data)

Reproduction Steps

[Schema Inaccuracy] In SearchContacts, `pagination.per_page` is not defined.

Schema Inaccuracy

There is an inconsistency between the schema of SearchContacts and what is documented in the API docs:

API docs documentation states that the pagination.per_page is to be provided in the request body to specify the number of items to return.

However, both v2.9 and Unstable do not include this property, and instead define pagination.page.
See the following lines (for v2.9):

• Intercom-OpenAPI/descriptions/2.9/api.intercom.io.yaml

  Lines 14873 to 14885 in 2498a89

  	search_request:
  	description: Search using Intercoms Search APIs.
  	type: object
  	title: Search data
  	properties:
  	query:
  	oneOf:
  	- "$ref": "#/components/schemas/single_filter_search_request"
  	title: Single filter search request
  	- "$ref": "#/components/schemas/multiple_filter_search_request"
  	title: multiple filter search request
  	pagination:
  	"$ref": "#/components/schemas/starting_after_paging"

• Intercom-OpenAPI/descriptions/2.9/api.intercom.io.yaml

  Lines 15143 to 15153 in 2498a89

  	starting_after_paging:
  	title: StartingAfterPaging
  	type: object
  	nullable: true
  	properties:
  	page:
  	type: integer
  	example: 2
  	starting_after:
  	type: string
  	example: 1HaSB+xrOyyMXAkS/c1RteCL7BzOzTvYjmjakgTergIH31eoe2v4/sbLsJWP\nIncfQLD3ouPkZlCwJ86F\n

I tested real API calls with both pagination.per_page and pagination.page and the former is the one that works as expected; the latter has no effect.

⚠️ The component starting_after_paging, which is relied on for pagination of SearchContacts ' request body, also appear here:

Intercom-OpenAPI/descriptions/2.9/api.intercom.io.yaml

Line 13547 in 2498a89

"$ref": "#/components/schemas/starting_after_paging"

This reference expects pagination.page and not pagination.per_page as it is a reference of the next page.

The two must be decoupled.

Expected

We would expect to have pagination.per_page instead of pagination.page in the OpenAPI spec.

Reproduction Steps

N/A.

Spelling Mistake

Just realized you don't accept pull requests so creating an issue.

Line 2279 (in latest version 2.9) has a spelling mistake. Should be "detach" instead of "dettach" :)

Remove "payload preview" from webhook references

this doesn't look like it's available any longer so needs to be removed

Does not compile for Golang

The 2.9 version (perhaps others) does not compile for Go.

There are duplicate type declarations for TicketType and TicketTypes.

One of the duplicates needs an x-go-name attribute to allow api-codegen to be able to generate working Go code.

Duplicate Paramater

/tickets/{ticket_id}/reply in v2.9 (possibly others) has a duplicate paramater:

"/tickets/{ticket_id}/reply":
    parameters:
    - name: ticket_id
      in: path
      description: ticket_id
      required: true
      schema:
        type: string
    post:
      summary: Create a ticket reply
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ticket_id
        in: path
        required: true
        description: The unique identifier for the ticket which is given by Intercom
        schema:
          type: string

The first parameters block is redundant and caused generation of code for Go to fail.

error generating code: error creating operation definitions: path '/tickets/{ticket_id}/reply' has 1 positional parameters, but spec has 2 declared

[Schema Inaccuracy] Fields not marked as required

Schema Inaccuracy

The response fields are not marked as required thus creating | undefined types in code generation tools

Expected

For example, the tag definition:

 tag:
      title: Tag
      type: object
      x-tags:
      - Tags
      description: A tag allows you to label your contacts, companies, and conversations
        and list them using that tag.
      properties:
        type:
          type: string
          description: value is "tag"
          example: tag
        id:
          type: string
          description: The id of the tag
          example: '123456'
        name:
          type: string
          description: The name of the tag
          example: Test tag
        applied_at:
          type: integer
          format: date-time
          description: The time when the tag was applied to the object
          example: 1663597223
        applied_by:
          "$ref": "#/components/schemas/reference"

should be:

tag:
      title: Tag
      type: object
      x-tags:
      - Tags
      description: A tag allows you to label your contacts, companies, and conversations
        and list them using that tag.
      properties:
        type:
          type: string
          required: true
          description: value is "tag"
          example: tag
        id:
          type: string
          required: true
          description: The id of the tag
          example: '123456'
        name:
          type: string
          required: true
          description: The name of the tag
          example: Test tag
        applied_at:
          required: true
          type: integer
          format: date-time
          description: The time when the tag was applied to the object
          example: 1663597223
        applied_by:
          required: true
          "$ref": "#/components/schemas/reference"

Reproduction Steps

Please see attached conversation
drwpow/openapi-typescript#1422 (comment)

And repro repo
https://github.com/cipriancaba/openapi-typescript