Quickstart Tutorial

Overview

In this tutorial, you’ll learn how to:

Generate an API key
Query your feedback data
Create new feedback via the API
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

Navigate to app.tellscope.io and sign in.

Open Settings

Click your profile icon in the bottom-left corner and select Settings.

Generate API Key

Scroll to the API section and click Generate API Key.Your key will look like this:

tellscp_sk_42Xk9mPqR7vL2nYwZ8jK...

Store it securely

Copy the key immediately—you won’t be able to see it again. Store it in an environment variable:

export TELLSCOPE_API_KEY="tellscp_sk_YOUR_KEY_HERE"

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

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:

query GetRecentFeedback {
  feedbackItems(
    apiKey: "tellscp_sk_YOUR_KEY"
    take: 5
  ) {
    items {
      id
      title
      source
      sentiment
      createdAt
    }
    total
  }
}

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 } }"
  }'

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);

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']}")

Response

{
  "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
    }
  }
}

If you see your feedback data, you’re connected! 🎉

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

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
  }
}

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);

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']}")

Response

{
  "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:

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:

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

Pagination

Use skip and take for pagination:

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

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

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

Get Account Details

query GetAccount {
  accountItem(
    apiKey: "tellscp_sk_YOUR_KEY"
    id: "acc_xyz789"
  ) {
    id
    name
    domain
    score
    churnRisk
    tags
  }
}

What’s Next?

API Reference

Explore all available queries and mutations

Authentication

Learn about API key security best practices

Feedback Endpoints

Deep dive into feedback operations

Error Handling

Handle errors gracefully in your integration

Example: Complete Integration

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

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);

You now have all the tools to build powerful integrations with Tellscope!

​Overview

​Step 1: Get Your API Key

​Step 2: Make Your First Query

​Response

​Step 3: Create Feedback via API

​Response

​Step 4: Filter and Paginate

​Filter by Sentiment

​Filter by Source

​Pagination

​Combine Filters

​Step 5: Query Contacts and Accounts

​List Contacts

​Get Account Details

​What’s Next?

API Reference

Authentication

Feedback Endpoints

Error Handling

​Example: Complete Integration

Overview

Step 1: Get Your API Key

Step 2: Make Your First Query

Response

Step 3: Create Feedback via API

Response

Step 4: Filter and Paginate

Filter by Sentiment

Filter by Source

Pagination

Combine Filters

Step 5: Query Contacts and Accounts

List Contacts

Get Account Details

What’s Next?

Example: Complete Integration