Skip to main content

​
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

1

Log in to Tellscope

Navigate to app.tellscope.io and sign in.
2

Open Settings

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

Generate API Key

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

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

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

​
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!