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

# Quickstart Tutorial

> Build your first Tellscope API integration in 10 minutes

## Overview

In this tutorial, you'll learn how to:

1. Generate an API key
2. Query your feedback data
3. Create new feedback via the API
4. Filter and paginate results

By the end, you'll have a working integration that can read and write feedback data.

***

## Step 1: Get Your API Key

<Steps>
  <Step title="Log in to Tellscope">
    Navigate to [app.tellscope.io](https://app.tellscope.io) and sign in.
  </Step>

  <Step title="Open Settings">
    Click your profile icon in the bottom-left corner and select **Settings**.
  </Step>

  <Step title="Generate API Key">
    Scroll to the **API** section and click **Generate API Key**.

    Your key will look like this:

    ```
    tellscp_sk_42Xk9mPqR7vL2nYwZ8jK...
    ```
  </Step>

  <Step title="Store it securely">
    Copy the key immediately—you won't be able to see it again. Store it in an environment variable:

    ```bash theme={null}
    export TELLSCOPE_API_KEY="tellscp_sk_YOUR_KEY_HERE"
    ```
  </Step>
</Steps>

<Warning>
  Never commit your API key to version control or expose it in client-side code.
</Warning>

***

## Step 2: Make Your First Query

The Tellscope API uses **GraphQL**. All requests go to a single endpoint:

```
POST https://api.tellscope.io/graphql
```

Let's fetch your 5 most recent feedback items:

<CodeGroup>
  ```graphql Query theme={null}
  query GetRecentFeedback {
    feedbackItems(
      apiKey: "tellscp_sk_YOUR_KEY"
      take: 5
    ) {
      items {
        id
        title
        source
        sentiment
        createdAt
      }
      total
    }
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.tellscope.io/graphql \
    -H "Content-Type: application/json" \
    -d '{
      "query": "query { feedbackItems(apiKey: \"'$TELLSCOPE_API_KEY'\", take: 5) { items { id title source sentiment createdAt } total } }"
    }'
  ```

  ```javascript Node.js theme={null}
  const TELLSCOPE_API_KEY = process.env.TELLSCOPE_API_KEY;

  const query = `
    query GetRecentFeedback {
      feedbackItems(apiKey: "${TELLSCOPE_API_KEY}", take: 5) {
        items {
          id
          title
          source
          sentiment
          createdAt
        }
        total
      }
    }
  `;

  const response = await fetch('https://api.tellscope.io/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query })
  });

  const { data } = await response.json();
  console.log(data.feedbackItems.items);
  ```

  ```python Python theme={null}
  import os
  import requests

  api_key = os.environ['TELLSCOPE_API_KEY']

  query = '''
    query GetRecentFeedback {
      feedbackItems(apiKey: "%s", take: 5) {
        items {
          id
          title
          source
          sentiment
          createdAt
        }
        total
      }
    }
  ''' % api_key

  response = requests.post(
      'https://api.tellscope.io/graphql',
      json={'query': query}
  )

  data = response.json()['data']
  for item in data['feedbackItems']['items']:
      print(f"{item['sentiment']}: {item['title']}")
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": {
    "feedbackItems": {
      "items": [
        {
          "id": "fb_a1b2c3",
          "title": "Love the new dashboard!",
          "source": "intercom",
          "sentiment": "positive",
          "createdAt": "2024-01-20T14:30:00Z"
        },
        {
          "id": "fb_d4e5f6",
          "title": "Export feature not working",
          "source": "zendesk",
          "sentiment": "negative",
          "createdAt": "2024-01-20T12:15:00Z"
        }
      ],
      "total": 1523
    }
  }
}
```

<Check>
  If you see your feedback data, you're connected! 🎉
</Check>

***

## Step 3: Create Feedback via API

Now let's create a new feedback item. This is useful for:

* Ingesting feedback from custom sources
* Building feedback widgets
* Importing historical data

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation CreateFeedback {
    addFeedbackItem(
      apiKey: "tellscp_sk_YOUR_KEY"
      input: {
        source: "api"
        title: "Feature request: Dark mode"
        content: "Would love to have a dark mode option for the dashboard. It would be easier on the eyes during late night work sessions."
        author: "Alex Chen"
        email: "alex@example.com"
        sentiment: "neutral"
        metadata: {
          category: "feature_request"
          priority: "medium"
        }
      }
    ) {
      id
      title
      status
      createdAt
    }
  }
  ```

  ```javascript Node.js theme={null}
  const mutation = `
    mutation CreateFeedback {
      addFeedbackItem(
        apiKey: "${TELLSCOPE_API_KEY}"
        input: {
          source: "api"
          title: "Feature request: Dark mode"
          content: "Would love to have a dark mode option..."
          author: "Alex Chen"
          email: "alex@example.com"
          sentiment: "neutral"
        }
      ) {
        id
        title
        createdAt
      }
    }
  `;

  const response = await fetch('https://api.tellscope.io/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query: mutation })
  });

  const { data } = await response.json();
  console.log('Created:', data.addFeedbackItem.id);
  ```

  ```python Python theme={null}
  mutation = '''
    mutation CreateFeedback {
      addFeedbackItem(
        apiKey: "%s"
        input: {
          source: "api"
          title: "Feature request: Dark mode"
          content: "Would love to have a dark mode option..."
          author: "Alex Chen"
          email: "alex@example.com"
          sentiment: "neutral"
        }
      ) {
        id
        title
        createdAt
      }
    }
  ''' % api_key

  response = requests.post(
      'https://api.tellscope.io/graphql',
      json={'query': mutation}
  )

  result = response.json()['data']['addFeedbackItem']
  print(f"Created feedback: {result['id']}")
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": {
    "addFeedbackItem": {
      "id": "fb_new123",
      "title": "Feature request: Dark mode",
      "status": "unread",
      "createdAt": "2024-01-20T16:45:00Z"
    }
  }
}
```

***

## Step 4: Filter and Paginate

Real-world integrations need to filter and paginate data. Here are common patterns:

### Filter by Sentiment

Find all negative feedback to prioritize urgent issues:

```graphql theme={null}
query NegativeFeedback {
  feedbackItems(
    apiKey: "tellscp_sk_YOUR_KEY"
    sentiment: "negative"
    take: 20
  ) {
    items {
      id
      title
      source
      author
      createdAt
    }
    total
  }
}
```

### Filter by Source

Get feedback from a specific integration:

```graphql theme={null}
query ZendeskFeedback {
  feedbackItems(
    apiKey: "tellscp_sk_YOUR_KEY"
    source: "zendesk"
    take: 50
  ) {
    items {
      id
      title
      sentiment
    }
    total
  }
}
```

### Pagination

Use `skip` and `take` for pagination:

```graphql theme={null}
query PaginatedFeedback {
  # Page 1: items 0-19
  feedbackItems(apiKey: "tellscp_sk_YOUR_KEY", skip: 0, take: 20) {
    items { id title }
    total
  }
}

query Page2 {
  # Page 2: items 20-39
  feedbackItems(apiKey: "tellscp_sk_YOUR_KEY", skip: 20, take: 20) {
    items { id title }
    total
  }
}
```

### Combine Filters

```graphql theme={null}
query FilteredResults {
  feedbackItems(
    apiKey: "tellscp_sk_YOUR_KEY"
    source: "intercom"
    sentiment: "negative"
    status: "unread"
    skip: 0
    take: 10
  ) {
    items {
      id
      title
      author
      createdAt
    }
    total
  }
}
```

***

## Step 5: Query Contacts and Accounts

You can also access contact and account data:

### List Contacts

```graphql theme={null}
query SearchContacts {
  contactItems(
    apiKey: "tellscp_sk_YOUR_KEY"
    search: "acme"
    take: 10
  ) {
    items {
      id
      name
      email
      company
      totalFeedbacks
    }
    total
  }
}
```

### Get Account Details

```graphql theme={null}
query GetAccount {
  accountItem(
    apiKey: "tellscp_sk_YOUR_KEY"
    id: "acc_xyz789"
  ) {
    id
    name
    domain
    score
    churnRisk
    tags
  }
}
```

***

## What's Next?

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore all available queries and mutations
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn about API key security best practices
  </Card>

  <Card title="Feedback Endpoints" icon="comments" href="/api-reference/feedback/list">
    Deep dive into feedback operations
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api-reference/introduction#error-handling">
    Handle errors gracefully in your integration
  </Card>
</CardGroup>

***

## Example: Complete Integration

Here's a complete example that syncs feedback to a Slack channel:

```javascript theme={null}
import Slack from '@slack/web-api';

const TELLSCOPE_API_KEY = process.env.TELLSCOPE_API_KEY;
const slack = new Slack.WebClient(process.env.SLACK_TOKEN);

async function syncNegativeFeedback() {
  // Fetch negative feedback from the last hour
  const query = `
    query {
      feedbackItems(
        apiKey: "${TELLSCOPE_API_KEY}"
        sentiment: "negative"
        status: "unread"
        take: 10
      ) {
        items {
          id
          title
          content
          author
          source
        }
      }
    }
  `;

  const response = await fetch('https://api.tellscope.io/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query })
  });

  const { data } = await response.json();
  
  for (const feedback of data.feedbackItems.items) {
    await slack.chat.postMessage({
      channel: '#customer-feedback',
      text: `🔴 *Negative Feedback*\n*${feedback.title}*\nFrom: ${feedback.author} via ${feedback.source}\n\n${feedback.content}`
    });
  }
}

// Run every 15 minutes
setInterval(syncNegativeFeedback, 15 * 60 * 1000);
```

<Check>
  You now have all the tools to build powerful integrations with Tellscope!
</Check>