API reference

Reports

10 endpoints in this group.

Report overview

GET/api/v1/reports/overview

This month's message and AI usage (organization-wide), contact, opted-in and handed-off conversation counts; the selected period's breakdown by bot, hour and day; a campaign summary. A member only sees data from the bots they can access. Scope: reports:read.

Scope
reports:read
SDK method
getReportOverview · get_report_overview
MCP tool
getReportOverviewread-only

Parameters

NameTypeRequiredDescription
daysqueryenumnoPeriod in days: 7, 30 or 90; default 307 | 30 | 90, default 30

Example request

curl -X GET "https://hiboty.com/api/v1/reports/overview" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "days": 1,
    "usage": {
      "messages": {
        "used": 1,
        "limit": 1
      },
      "ai_replies": {
        "used": 1,
        "limit": 1,
        "effective_limit": 1,
        "own_key": true
      },
      "ai_tokens": 1
    },
    "contacts": {
      "total": 1,
      "opted_in": 1
    },
    "conversations": {
      "total": 1,
      "handoff": 1
    },
    "bots": [
      {
        "name": "Hiboty",
        "incoming": 1,
        "ai": 1,
        "agent": 1
      }
    ],
    "hourly": [
      1
    ],
    "daily": [
      {
        "date": "string",
        "ai": 1,
        "agent": 1
      }
    ],
    "campaigns": {
      "total": 1,
      "completed": 1,
      "delivered": 1
    }
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Delivery telemetry

GET/api/v1/reports/delivery

The success rate of outgoing messages, failures by source and failure reasons. A member only sees data from the bots they can access. Scope: reports:read.

Scope
reports:read
SDK method
getDeliveryTelemetry · get_delivery_telemetry
MCP tool
getDeliveryTelemetryread-only

Parameters

NameTypeRequiredDescription
daysqueryenumnoPeriod in days: 7, 30 or 90; default 307 | 30 | 90, default 30

Example request

curl -X GET "https://hiboty.com/api/v1/reports/delivery" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "days": 1,
    "succeeded": 1,
    "failed": 1,
    "success_rate": 1,
    "recovered": 1,
    "sources": [
      {
        "sender": "string",
        "succeeded": 1,
        "failed": 1
      }
    ],
    "reasons": [
      {
        "reason": "string",
        "count": 1
      }
    ],
    "samples": [
      {
        "error": "string",
        "count": 1
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Agent performance

GET/api/v1/reports/agents

First reply and resolution times, SLA compliance, waiting conversations and per-agent counts. A member only sees data from the bots they can access. Scope: reports:read.

Scope
reports:read
SDK method
getAgentReport · get_agent_report
MCP tool
getAgentReportread-only

Parameters

NameTypeRequiredDescription
daysqueryenumnoPeriod in days: 7, 30 or 90; default 307 | 30 | 90, default 30

Example request

curl -X GET "https://hiboty.com/api/v1/reports/agents" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "days": 1,
    "handoffs": 1,
    "resolved": 1,
    "first_reply_median_seconds": 1,
    "resolution_average_seconds": 1,
    "sla_target_minutes": 1,
    "sla_compliance": 1,
    "waiting": 1,
    "oldest_waiting_seconds": 1,
    "agents": [
      {
        "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Hiboty",
        "open": 1,
        "replies": 1,
        "first_reply_median_seconds": 1
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Satisfaction report

GET/api/v1/reports/csat

Average score, satisfied rate, the 1-5 distribution and per-agent averages. A member only sees data from the bots they can access. Scope: reports:read.

Scope
reports:read
SDK method
getCsatReport · get_csat_report
MCP tool
getCsatReportread-only

Parameters

NameTypeRequiredDescription
daysqueryenumnoPeriod in days: 7, 30 or 90; default 307 | 30 | 90, default 30

Example request

curl -X GET "https://hiboty.com/api/v1/reports/csat" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "days": 1,
    "enabled": true,
    "responses": 1,
    "average": 1,
    "satisfied_rate": 1,
    "distribution": [
      1
    ],
    "agents": [
      {
        "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Hiboty",
        "responses": 1,
        "average": 1,
        "satisfied_rate": 1
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

AI quality report

GET/api/v1/reports/ai-quality

A summary of the feedback agents gave on AI replies. A member only sees data from the bots they can access. Scope: reports:read.

Scope
reports:read
SDK method
getAiQualityReport · get_ai_quality_report
MCP tool
getAiQualityReportread-only

Parameters

NameTypeRequiredDescription
daysqueryenumnoPeriod in days: 7, 30 or 90; default 307 | 30 | 90, default 30

Example request

curl -X GET "https://hiboty.com/api/v1/reports/ai-quality" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "days": 1,
    "ai_replies": 1,
    "rated": 1,
    "liked": 1,
    "disliked": 1,
    "like_rate": 1,
    "coverage": 1,
    "attributed_replies": 1,
    "unsourced_replies": 1,
    "unsourced_rate": 1
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Audience cohorts

GET/api/v1/reports/cohorts

Contact cohorts of the last 8 weeks and how many wrote to the bot again in later weeks. A member only sees data from the bots they can access. Scope: reports:read.

Scope
reports:read
SDK method
getCohortReport · get_cohort_report
MCP tool
getCohortReportread-only

Example request

curl -X GET "https://hiboty.com/api/v1/reports/cohorts" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "new_contacts": 1,
    "first_week_return_rate": 1,
    "cohorts": [
      {
        "week": "string",
        "size": 1,
        "rates": [
          1
        ]
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Revenue attribution and ROI

GET/api/v1/reports/revenue

Revenue (Mini App and store orders), cost and ROI attributed to campaigns, acquisition links and click-to-WhatsApp ads; store orders matched to bot conversations are in totals.store. Pass from and to together (YYYY-MM-DD, organization day); without them, the last 30 days. The range is at most 1 year. A member only sees data from the bots they can access. Scope: reports:read.

Scope
reports:read
SDK method
getRevenueReport · get_revenue_report
MCP tool
getRevenueReportread-only

Parameters

NameTypeRequiredDescription
fromquerydatenoStart day (YYYY-MM-DD)
toquerydatenoEnd day, inclusive (YYYY-MM-DD)

Example request

curl -X GET "https://hiboty.com/api/v1/reports/revenue" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "from": "string",
    "to": "string",
    "range_clamped": true,
    "campaigns": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Hiboty",
        "bot_name": "string",
        "channel": "string",
        "summary": {
          "orders": 1,
          "cancelled": 1,
          "refunded": 1,
          "gross": {
            "amounts": {},
            "stars": 1
          },
          "net": {
            "amounts": {},
            "stars": 1
          },
          "unpriced_items": 1
        },
        "cost": {
          "amount": 1,
          "currency": "USD",
          "mixed": {
            "key": 1
          }
        },
        "manual_cost": {
          "amount": 1,
          "currency": "USD"
        },
        "roi": {
          "value": 1,
          "reason": "string"
        }
      }
    ],
    "links": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Hiboty",
        "bot_name": "string",
        "channel": "string",
        "summary": {
          "orders": 1,
          "cancelled": 1,
          "refunded": 1,
          "gross": {
            "amounts": {},
            "stars": 1
          },
          "net": {
            "amounts": {},
            "stars": 1
          },
          "unpriced_items": 1
        },
        "cost": {
          "amount": 1,
          "currency": "USD",
          "mixed": {
            "key": 1
          }
        },
        "manual_cost": {
          "amount": 1,
          "currency": "USD"
        },
        "roi": {
          "value": 1,
          "reason": "string"
        },
        "code": "ornek",
        "new_contacts": 1,
        "cost_per_contact": {
          "value": 1,
          "currency": "USD",
          "reason": "string"
        }
      }
    ],
    "ads": [
      {
        "id": "string",
        "name": "Hiboty",
        "source_type": "string",
        "source_url": "https://example.com/a.png",
        "new_contacts": 1,
        "summary": {
          "orders": 1,
          "cancelled": 1,
          "refunded": 1,
          "gross": {
            "amounts": {},
            "stars": 1
          },
          "net": {
            "amounts": {},
            "stars": 1
          },
          "unpriced_items": 1
        },
        "cost": {
          "amount": 1,
          "currency": "USD",
          "mixed": {
            "key": 1
          }
        },
        "roi": {
          "value": 1,
          "reason": "string"
        },
        "cost_per_contact": {
          "value": 1,
          "currency": "USD",
          "reason": "string"
        }
      }
    ],
    "totals": {
      "campaigns": {
        "orders": 1,
        "cancelled": 1,
        "refunded": 1,
        "gross": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "net": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "unpriced_items": 1
      },
      "links": {
        "orders": 1,
        "cancelled": 1,
        "refunded": 1,
        "gross": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "net": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "unpriced_items": 1
      },
      "store": {
        "orders": 1,
        "cancelled": 1,
        "refunded": 1,
        "gross": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "net": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "unpriced_items": 1
      },
      "ads": {
        "orders": 1,
        "cancelled": 1,
        "refunded": 1,
        "gross": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "net": {
          "amounts": {
            "key": 1
          },
          "stars": 1
        },
        "unpriced_items": 1
      }
    },
    "conversions": {
      "campaigns": {
        "target": "string",
        "total": 1,
        "converted": [
          {
            "currency": "USD",
            "amount": 1,
            "equivalent": 1
          }
        ],
        "unconverted": {
          "key": 1
        },
        "stars": 1
      },
      "links": {
        "target": "string",
        "total": 1,
        "converted": [
          {
            "currency": "USD",
            "amount": 1,
            "equivalent": 1
          }
        ],
        "unconverted": {
          "key": 1
        },
        "stars": 1
      },
      "store": {
        "target": "string",
        "total": 1,
        "converted": [
          {
            "currency": "USD",
            "amount": 1,
            "equivalent": 1
          }
        ],
        "unconverted": {
          "key": 1
        },
        "stars": 1
      },
      "ads": {
        "target": "string",
        "total": 1,
        "converted": [
          {
            "currency": "USD",
            "amount": 1,
            "equivalent": 1
          }
        ],
        "unconverted": {
          "key": 1
        },
        "stars": 1
      }
    },
    "exchange_rate": {
      "usd_try": 1,
      "date": "string"
    },
    "out_of_scope": {
      "miniapp_orders": 1,
      "orders_without_contact": 1,
      "store_orders": 1,
      "store_unmatched": 1
    },
    "truncated": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Plan and usage

GET/api/v1/reports/usage

The plan, limits, this month's message and AI reply usage, token totals, and extra AI and message credits. Organization-wide. With group_by=bot|channel, the breakdown field has this month's outgoing messages, AI replies, media and Meta estimate per bot or channel; the rows add up to the overall totals. A member only sees the bots they can access in the breakdown. Scope: reports:read.

Scope
reports:read
SDK method
getUsageReport · get_usage_report
MCP tool
getUsageReportread-only

Parameters

NameTypeRequiredDescription
group_byqueryenumnoUsage breakdown: bot or channelbot | channel

Example request

curl -X GET "https://hiboty.com/api/v1/reports/usage" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "plan": "string",
    "limits": {
      "bots": 1,
      "seats": 1,
      "workspaces": 1,
      "monthly_messages": 1,
      "monthly_ai_replies": 1,
      "campaigns": true,
      "api": true,
      "miniapps": true
    },
    "messages": {
      "used": 1,
      "limit": 1,
      "extra_credits": 1
    },
    "ai_replies": {
      "used": 1,
      "limit": 1,
      "extra_credits": 1
    },
    "ai_tokens": {
      "input": 1,
      "output": 1,
      "total": 1
    },
    "breakdown": {
      "group_by": "bot",
      "rows": [
        {
          "key": "sehir",
          "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "Hiboty",
          "channel": "telegram",
          "messages_out": 1,
          "ai_replies": 1,
          "media": 1,
          "meta_estimate_usd": 1
        }
      ],
      "totals": {
        "messages_out": 1,
        "ai_replies": 1,
        "media": 1,
        "meta_estimate_usd": 1
      }
    }
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Sets the cost of a campaign or link

PUT/api/v1/reports/costs/{kind}/{id}

The total cost used for ROI; amount null clears it. The change goes to the audit log with old and new values. Needs admin permission. Scope: campaigns:write.

Scope
campaigns:write
SDK method
setReportCost · set_report_cost
MCP tool
setReportCost

Parameters

NameTypeRequiredDescription
kindpathenumyesKindcampaign | link
idpathuuidyesID

Body fields

NameTypeRequiredDescription
amountnumber | nullyesval ≥ 0
currencyenumnoTRY | USD | EUR

Example request

curl -X PUT "https://hiboty.com/api/v1/reports/costs/campaign/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":1250.5,"currency":"TRY"}'

Example response (200)

JSON
{
  "data": {
    "kind": "campaign",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "amount": 1,
    "currency": "USD"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Imports ad costs

POST/api/v1/reports/costs/import

Writes period costs for a campaign (kind campaign, ref campaign ID), an acquisition link (link, ref link code) or a click-to-WhatsApp ad (ad, ref Meta ad ID source_id). Send csv or rows; the CSV header has kind, ref, amount, currency, period_start and period_end columns (Turkish names also accepted; comma, semicolon or tab separated). The same target, period and currency is updated. Invalid rows come back in errors and the rest are written. Costs whose period overlaps the report range are added to getRevenueReport ROI. At most 1000 rows. Spend is not pulled from an ads API. Needs admin permission. Scope: campaigns:write.

Scope
campaigns:write
SDK method
importReportCosts · import_report_costs
MCP tool
importReportCosts

Body fields

NameTypeRequiredDescription
csvstringnoCSV text (the first row is the header)len ≤ 500000
rowsobject[]no
rows[].kindenumyescampaign | link | ad
rows[].refstringyeslen ≤ 200
rows[].amountnumberyesval ≥ 0
rows[].currencyenumyesTRY | USD | EUR
rows[].period_startdateyes
rows[].period_enddateyes

Example request

curl -X POST "https://hiboty.com/api/v1/reports/costs/import" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"csv":"tur,hedef,tutar,para_birimi,baslangic,bitis\nad,120226305854810726,1250.50,TRY,2026-11-01,2026-11-30\nlink,INSTA-KASIM,800,TRY,2026-11-01,2026-11-30"}'

Example response (200)

JSON
{
  "data": {
    "imported": 1,
    "updated": 1,
    "errors": [
      {
        "line": 1,
        "error": "tur"
      }
    ],
    "total": 1
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.