Ingestion API

The ingestion API can be used to upload data to Birdie directly. Clients upload data by making an HTTP PUT for each record they want to upload.

The request must include a Birdie API key in an HTTP header in the form:

Authorization: ApiKey {api-key}

To generate an API key, you can reach out to the Birdie team and we will provide you one.

Response status codes

• 201 Created on success

• 400 Bad Request if the request body is invalid (response body will be a JSON object with an error message)

• 401 Unauthorized if the API key is missing or invalid

• 503 Service Unavailable if too many requests are being made in a short amount of time

We suggest making up to 100 requests per second (6000 per minute) to the Birdie API to avoid 5XX errors.

JSON formats

The uploaded data has to be in JSON format. Schema definitions for each type are available at: https://api.birdie.ai/ingestion/schemas

Types of uploads

Conversations and Messages

A conversation is an identifier of a discussion between one or more users (e.g., a support ticket or a GitHub issue).

A message is part of a conversation; a conversation is composed of messages.

Conversations and messages must be uploaded together (we suggest uploading the conversation first, then its messages). Conversations don't appear inside Birdie if they don't have an associated conversation message and vice-versa. Birdie calculates a summary for each conversation based on its messages, which is shown in the feed and can be expanded to see individual messages.

Feedbacks

A single feedback record posted by a user (e.g., NPS response or app review). Feedbacks are displayed alongside conversation summaries in the feed.

Audience: Accounts and Users (optional)

Accounts and users are optional records to further segment feedbacks and conversations. Use account-id and author-id fields inside the kind fields of feedbacks or conversation messages. After uploading feedbacks/conversations, you can upload accounts and users.

Kinds

For conversations, messages, and feedbacks, the schema includes a kind field to distinguish different kinds (e.g., support_ticket, review). Kinds add fields specific to the origin of the data.

Kinds are used to add more fields that are more specific to the origin of the data.

For example, for conversations and messages, the Zendesk Tickets example falls under the support_ticket kind. The app store user review example falls under the review kind.

We have multiple kinds, which can be listed here: https://api.birdie.ai/ingestion/schemas

You will need to analyze your source of data and see which record type (so Conversation vs Feedbacks) and which Kind best fits your data.

The value of the kind field within a feedback, conversation or conversation message is always an object with two fields:

• name: specifies the kind

• fields: contains data specific to this kind.

The valid kinds and their schemas are documented at the URL given above.

Other common concepts

• Path parameters in endpoints are identifiers for records. They should be strings (alpha-numerical suggested) and must be unique for records that co-exist in your Birdie account.

• Common fields across record types:

  • additional_fields: lets clients upload any fields that don't fit the pre-defined schema (can be mapped to custom fields in Birdie — contact Birdie team for setup).

  • batch_id: optional field to group uploaded records into a batch. Guidelines:

    1. Upload all records with the same batch_id within 24 hours.

    2. Avoid using a different batch_id for each record (this would create too many batches).

Endpoints

There are five endpoints to upload different types of data.

Conversations endpoint

PUT /ingestion/conversations/{conversation-id}

Use to create or update a conversation. Updates overwrite the entire record (no partial updates).

The messages belonging to the conversation are uploaded separately.

Example 1 - Conversation of kind support_ticket

curl

curl https://api.birdie.ai/ingestion/conversations/123 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "kind": {
      "name": "support_ticket",
      "fields": {
        "subject": "Account reset",
        "status": "open",
        "priority": "normal",
        "channel": "email"
      }
    },
    "additional_fields": {
      "ticket_opened_at": "2024-01-01T00:00:00Z"
    }
  }'

Example 2 - Conversation of kind issue

curl

curl https://api.birdie.ai/ingestion/conversations/issue-1 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "kind": {
      "name": "issue",
      "fields": {
        "project_id": "birdie/repository",
        "project_name": "repository",
        "status": "open",
        "title": "Doesnt work after update 1.01"
      }
    },
    "additional_fields": {
      "issue_opened_at": "2024-01-01T00:00:00Z",
      "repository_tags": ["repo"]
    }
  }'

Messages endpoint

PUT /ingestion/conversations/{conversation-id}/messages/{message-id}

Use to create or update a message that belongs to a conversation. Updates overwrite the entire record (no partial updates).

The conversation ID must match a conversation uploaded separately. Order of uploads (conversation vs messages) is not important.

Example 1 - Message of kind support_ticket

curl

curl https://api.birdie.ai/ingestion/conversations/123/messages/456 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "kind": {
      "name": "support_ticket",
      "fields": {
        "author_id": "author-1",
        "author_name": "John Doe",
        "author_type": "Agent"
      }
    },
    "text":"Hello, My name is John! Im here to assist you today.",
    "language":"en",
    "posted_at":"2024-01-01T00:00:00Z",
    "additional_fields": {
      "high_priority": true
    }
  }'

Example 2 - First message of kind issue by User

curl

curl https://api.birdie.ai/ingestion/conversations/issue-1/messages/issue-msg-1 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "kind": {
      "name": "issue",
      "fields": {
        "author_id": "engineer123",
        "author_name": "John"
      }
    },
    "text":"Since the last update, I cant get the service to work!",
    "language":"en",
    "posted_at":"2024-01-01T10:00:00Z",
    "additional_fields": {
      "thumbs_up": 5,
      "thumbs_down": 3
    }
  }'

Example 3 - Second message of kind issue by another user

curl

curl https://api.birdie.ai/ingestion/conversations/issue-1/messages/issue-msg-2 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "kind": {
      "name": "issue",
      "fields": {
        "author_id": "contributor456",
        "author_name": "Josh"
      }
    },
    "text":"Try rolling back to the last version, that worked for me",
    "language":"en",
    "posted_at":"2024-01-01T10:15:00Z",
    "additional_fields": {
      "thumbs_down": 10
    }
  }'

Feedbacks endpoint

PUT /ingestion/feedbacks/{feedback-id}

Use to create or update feedbacks that don't belong to a conversation. Updates overwrite the entire record (no partial updates).

Example 1 - Feedback of kind review

curl

curl https://api.birdie.ai/ingestion/feedbacks/abcd-123 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "posted_at": "2024-01-01T00:00:00Z",
    "text": "Excellent app",
    "language": "en",
    "kind": {
      "name": "review",
      "fields": {
        "owner": "Owner",
        "rating": 5.0
      }
    },
    "additional_fields": {
      "author": "John Doe",
      "device": "Android"
    }
  }'

Example 2 - Feedback of kind nps

curl

curl https://api.birdie.ai/ingestion/feedbacks/xyzw-451 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "posted_at": "2024-01-01T00:00:00Z",
    "text": "Im always recommending this service to my friends!",
    "language":"en",
    "kind": {
      "name": "nps",
      "fields": {
        "author_id": "john123",
        "author_name": "John Doe",
        "account_id": "companyABC",
        "title": "[NPS 2024] How Likely are you to recommend Birdie?",
        "rating": 10
      }
    },
    "additional_fields": {
      "classification": "promoter"
    }
  }'

Accounts endpoint

PUT /ingestion/audience/accounts/{account-id}

Use to create or update an account. Updates overwrite the entire record (no partial updates).

Example - Match uploaded NPS Feedback

curl

curl https://api.birdie.ai/ingestion/audience/accounts/companyABC \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "name": "Doe Inc.",
    "website": "https://example.com",
    "additional_fields": {
      "key_account": true
    }
  }'

Users endpoint

PUT /ingestion/audience/users/{user-id}

Use to create or update a user. Updates overwrite the entire record (no partial updates).

Example - Match uploaded NPS Feedback

curl

curl https://api.birdie.ai/ingestion/audience/users/john123 \
  -H 'Authorization: ApiKey {api-key}' \
  -H 'content-type: application/json' \
  -X PUT -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "additional_fields": {
      "key_user": true
    }
  }'

Results If you successfully managed to execute the previous requests, you should see the following results in your Birdie Feed.