API reference

Campaigns

17 endpoints in this group.

Lists campaigns

GET/api/v1/campaigns

Scope
read
SDK method
listCampaigns · list_campaigns
MCP tool
listCampaignsread-only

Paginated

Parameters

NameTypeRequiredDescription
bot_idqueryuuidnoThis bot only
statusqueryenumnoStatus filter; any other value returns 400draft | pending_approval | approved | sending | completed | failed | cancelled
limitqueryintegernoPage size (1–200, default 100); 400 if it isn't an integerval 1–200, default 100
cursorquerystringnonext_cursor from the previous response (opaque; older date-time cursors are also accepted)

Example request

curl -X GET "https://hiboty.com/api/v1/campaigns?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "status": "string",
      "body": "string",
      "template_name": "string",
      "topic": "string",
      "audience_count": 1,
      "sent_count": 1,
      "failed_count": 1,
      "scheduled_at": "2026-11-06T09:00:00.000Z",
      "started_at": "2026-11-06T09:00:00.000Z",
      "completed_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z",
      "best_time": true,
      "paused_at": "2026-11-06T09:00:00.000Z",
      "pause_reason": "hata_orani"
    }
  ],
  "next_cursor": "string"
}

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.

Creates a campaign (awaits approval)

POST/api/v1/campaigns

The campaign is created as "pending_approval" and isn't sent until an admin approves it in the dashboard; the API can't start sending. A Telegram bot needs body (body_b for A/B), a WhatsApp bot needs an approved template. If the organization's content policy is on, the text, template parameters and image URL are checked; a blocked request returns 422 content_policy. A wrong segment field returns 400; if no contact matches the filter it returns 409 empty_audience and never falls back to the whole audience. If the person who created the key (for OAuth, who granted access) hasn't verified their email, it returns 403 email_not_verified. Use Idempotency-Key to avoid duplicates on retries. Scope: write.

Scope
write
SDK method
createCampaign · create_campaign
MCP tool
createCampaignexternal effect

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Valid for 24 hours per organization, endpoint and key: the same key with the same body returns the first response unchanged (Idempotency-Replayed: true) and the action isn't repeated. A different body returns 409 idempotency_conflict; while the first request is running you get 409 idempotency_in_progress with Retry-After. 5xx and 429 responses aren't stored, so you can retry with the same key.len 1–255

Body fields

NameTypeRequiredDescription
bot_iduuidyes
namestringyeslen 2–120
bodystringnoTelegram text; you can use the {{ad}} and {{tercihler}} variableslen 5–4000
body_bstringnoSecond text for a Telegram A/B testlen 5–4000
media_urlstringnoTelegram image (https or upload address)len ≤ 500
templateobjectnoApproved WhatsApp template; A/B test with params_b
template.namestringyes
template.languagestringyes
template.paramsstring[]no
template.params_bstring[]no
topicstringnoTopic: duyuru, firsat, bilgilendirme, etkinlik, yeni_urun
scheduled_atdate-timenoSend at a later date
best_timebooleannoSend at the best time: the time is chosen from the bot's past engagement together with the organization's time zone, quiet hours and business-hours rules. Can't be combined with scheduled_at; with no suggestion, 409 best_time_unavailable.
segmentobjectnoAudience filter; conditions combine with AND. If it's missing or {}, all of the bot's consenting contacts are selected. An unknown field, invalid value or empty filter returns 400; if no one matches you get 409 empty_audience and the campaign never falls back to the whole audience.
segment.include_tagsstring[]noInclude by these tags (case-insensitive)items ≤ 20
segment.exclude_tagsstring[]noExclude anyone with one of these tagsitems ≤ 20
segment.matchenumnoinclude_tags: any of them (any) or all of them (all)any | all, default "any"
segment.last_seenobjectnoExactly one: within_days (seen in the last N days) or older_than_days (not seen for more than N days, including never seen)fields 1–1
segment.last_seen.within_daysintegernoval 1–3650
segment.last_seen.older_than_daysintegernoval 1–3650
segment.orderenumnoPlaced a Mini App order (placed) or hasn't (none)placed | none
segment.sourcestring[]noAny of the acquisition source codes; "-" selects contacts without a linkitems ≤ 20
segment.fieldsobject[]noCustom field conditions (all must match)items ≤ 5
segment.fields[].keystringyesCustom field key
segment.fields[].typeenumyestext | number | date | choice
segment.fields[].openumyesgt/lt with number and date only, contains with text onlyexists | empty | eq | neq | gt | lt | contains
segment.fields[].valuestring | numbernoRequired except for exists and empty

Example request

curl -X POST "https://hiboty.com/api/v1/campaigns" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","name":"November sale","body":"Hello {{ad}}, our November sale has started!","segment":{"include_tags":["vip"]}}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "status": "string",
    "body": "string",
    "template_name": "string",
    "topic": "string",
    "audience_count": 1,
    "sent_count": 1,
    "failed_count": 1,
    "scheduled_at": "2026-11-06T09:00:00.000Z",
    "started_at": "2026-11-06T09:00:00.000Z",
    "completed_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "best_time": true,
    "paused_at": "2026-11-06T09:00:00.000Z",
    "pause_reason": "hata_orani"
  }
}

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.email_not_verified
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.empty_audience
  • 422Blocked by the content policy (content_policy).content_policy
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).

Campaign and variant results

GET/api/v1/campaigns/{id}

Scope
read
SDK method
getCampaign · get_campaign
MCP tool
getCampaignread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesCampaign ID

Example request

curl -X GET "https://hiboty.com/api/v1/campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "status": "string",
    "body": "string",
    "template_name": "string",
    "topic": "string",
    "audience_count": 1,
    "sent_count": 1,
    "failed_count": 1,
    "scheduled_at": "2026-11-06T09:00:00.000Z",
    "started_at": "2026-11-06T09:00:00.000Z",
    "completed_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "best_time": true,
    "paused_at": "2026-11-06T09:00:00.000Z",
    "pause_reason": "hata_orani",
    "results": [
      {
        "variant": "string",
        "audience": 1,
        "sent": 1,
        "failed": 1,
        "replied": 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.
  • 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.

Updates a campaign that hasn't started

PATCH/api/v1/campaigns/{id}

Only draft and pending_approval campaigns can change; any other status returns 409 campaign_locked. The same checks as createCampaign apply: content policy (422 content_policy), segment, empty audience (409 empty_audience), approved template on WhatsApp. A changed campaign needs approval again: the status becomes pending_approval, approval details are cleared and whoever made the change counts as its creator (with four-eyes on they can't approve their own text; a change made with an API key can't be approved in the dashboard under four-eyes). The API can't start a send: there is no approval endpoint, a campaign starts only with four-eyes approval in the dashboard. Set body_b, media_url, topic or scheduled_at to null to clear them. Scope: campaigns:write.

Scope
campaigns:write
SDK method
updateCampaign · update_campaign
MCP tool
updateCampaign

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Body fields

NameTypeRequiredDescription
namestringnolen 2–120
bodystringnolen 5–4000
body_bstring | nullnolen 5–4000
media_urlstring | nullnolen ≤ 500
templateobjectno
template.namestringyeslen 1–200
template.languagestringyeslen 1–20
template.paramsstring[]no
template.params_bstring[]no
topicstring | nullnolen ≤ 40
scheduled_atdate-time | nullno
segmentobjectnoTag, last seen, order, source, custom field and temperature conditions; same format as createCampaign. An empty object means all of the bot's consenting contacts.

Example request

curl -X PATCH "https://hiboty.com/api/v1/campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"November sale","body":"Hello, our November sale has started!"}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "status": "string",
    "body": "string",
    "template_name": "string",
    "topic": "string",
    "audience_count": 1,
    "sent_count": 1,
    "failed_count": 1,
    "scheduled_at": "2026-11-06T09:00:00.000Z",
    "started_at": "2026-11-06T09:00:00.000Z",
    "completed_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "best_time": true,
    "paused_at": "2026-11-06T09:00:00.000Z",
    "pause_reason": "hata_orani"
  }
}

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).
  • 409The action isn't possible in this state; the code gives the reason.campaign_lockedempty_audience
  • 422Blocked by the content policy (content_policy).content_policy
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).

Deletes a campaign that was never sent

DELETE/api/v1/campaigns/{id}

Only draft, pending_approval and cancelled campaigns with no sends can be deleted; a started one returns 409 campaign_started. Needs admin permission. Scope: campaigns:write.

Scope
campaigns:write
SDK method
deleteCampaign · delete_campaign
MCP tool
deleteCampaignirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X DELETE "https://hiboty.com/api/v1/campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": 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.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.campaign_started
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Cancels an unfinished campaign

POST/api/v1/campaigns/{id}/cancel

If sending is in progress, remaining recipients aren't messaged; messages already sent aren't recalled. Scope: write.

Scope
write
SDK method
cancelCampaign · cancel_campaign
MCP tool
cancelCampaignirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesCampaign ID

Example request

curl -X POST "https://hiboty.com/api/v1/campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6/cancel" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "status": "string",
    "body": "string",
    "template_name": "string",
    "topic": "string",
    "audience_count": 1,
    "sent_count": 1,
    "failed_count": 1,
    "scheduled_at": "2026-11-06T09:00:00.000Z",
    "started_at": "2026-11-06T09:00:00.000Z",
    "completed_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "best_time": true,
    "paused_at": "2026-11-06T09:00:00.000Z",
    "pause_reason": "hata_orani"
  }
}

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).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Variant results and the A/B decision

GET/api/v1/campaigns/{id}/results

Audience, sent, failed and reply counts; the A/B stage and decision for an automatic winner. Read-only: the API can't start a send or approve one, a campaign starts with four-eyes approval in the dashboard. Scope: campaigns:read.

Scope
campaigns:read
SDK method
getCampaignResults · get_campaign_results
MCP tool
getCampaignResultsread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X GET "https://hiboty.com/api/v1/campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6/results" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "campaign_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "string",
    "audience_count": 1,
    "sent_count": 1,
    "failed_count": 1,
    "replied_count": 1,
    "variants": [
      {
        "variant": "a",
        "audience": 1,
        "sent": 1,
        "failed": 1,
        "replied": 1
      }
    ],
    "remaining_variants": [
      {
        "variant": "a",
        "audience": 1,
        "sent": 1,
        "failed": 1,
        "replied": 1
      }
    ],
    "ab_stage": "test",
    "ab_test_percent": 1,
    "ab_wait_hours": 1,
    "ab_decide_at": "2026-11-06T09:00:00.000Z",
    "ab_winner": "a",
    "ab_decision": {
      "reason": "string",
      "metric": "string",
      "a": {
        "sent": 1,
        "replied": 1,
        "read": 1
      },
      "b": {
        "sent": 1,
        "replied": 1,
        "read": 1
      }
    },
    "ab_decided_at": "2026-11-06T09:00:00.000Z"
  }
}

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.

Counts opted-in contacts matching a segment

POST/api/v1/campaigns/audience-count

Has no side effects and saves nothing. Only opted-in contacts count; with a topic, those who opted out of it are excluded. Scope: campaigns:read.

Scope
campaigns:read
SDK method
countCampaignAudience · count_campaign_audience
MCP tool
countCampaignAudienceread-only

Body fields

NameTypeRequiredDescription
bot_iduuidyes
segmentobjectnoTag, last seen, order, source, custom field and temperature conditions; same format as createCampaign. An empty object means all of the bot's consenting contacts.
topicstringnolen ≤ 40

Example request

curl -X POST "https://hiboty.com/api/v1/campaigns/audience-count" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","segment":{"include_tags":["vip"]},"topic":"firsat"}'

Example response (200)

JSON
{
  "data": {
    "audience_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.
  • 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.

Suggested send time

GET/api/v1/campaigns/best-time

The most engaging day and hour from the last 90 days of incoming messages that respects quiet and business hours; with too little data the suggestion is empty and reason says why. Scope: campaigns:read.

Scope
campaigns:read
SDK method
getCampaignBestTime · get_campaign_best_time
MCP tool
getCampaignBestTimeread-only

Parameters

NameTypeRequiredDescription
bot_idqueryuuidyesBot ID

Example request

curl -X GET "https://hiboty.com/api/v1/campaigns/best-time?bot_id=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "suggestion": {
      "weekday": 1,
      "hour": 1,
      "interactions": 1
    },
    "reason": "veri_az",
    "interactions": 1,
    "contacts": 1,
    "next_at": "2026-11-06T09:00:00.000Z",
    "timezone": "Europe/Istanbul"
  }
}

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.

Lists growth campaigns

GET/api/v1/growth-campaigns

Telegram growth campaigns (newest first, at most 100) with linked source counts, new contacts gained in the period and goal progress. A bot-restricted member only counts links of bots they can access. Scope: campaigns:read.

Scope
campaigns:read
SDK method
listGrowthCampaigns · list_growth_campaigns
MCP tool
listGrowthCampaignsread-only

Paginated

Parameters

NameTypeRequiredDescription
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque)

Example request

curl -X GET "https://hiboty.com/api/v1/growth-campaigns?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "goal_contacts": 1,
      "starts_on": "string",
      "ends_on": "string",
      "budget": {
        "amount": 1,
        "currency": "USD"
      },
      "status": "scheduled",
      "created_at": "2026-11-06T09:00:00.000Z",
      "updated_at": "2026-11-06T09:00:00.000Z",
      "acquisition_links": 1,
      "invite_links": 1,
      "new_contacts": 1,
      "progress_percent": 1
    }
  ],
  "next_cursor": "string"
}

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.

Creates a growth campaign

POST/api/v1/growth-campaigns

Creates a campaign with a contact goal, a period (organization days, end inclusive, at most 365 days) and an optional budget. Sources are linked with addGrowthCampaignSource. Needs admin permission. Scope: campaigns:write.

Scope
campaigns:write
SDK method
createGrowthCampaign · create_growth_campaign
MCP tool
createGrowthCampaign

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255

Body fields

NameTypeRequiredDescription
namestringyeslen 1–80
goal_contactsintegeryesval 1–10000000
starts_ondateyes
ends_ondateyes
budget_amountnumber | nullnoval ≥ 0
budget_currencyenumnoTRY | USD | EUR

Example request

curl -X POST "https://hiboty.com/api/v1/growth-campaigns" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"name":"Instagram launch","goal_contacts":500,"starts_on":"2026-11-01","ends_on":"2026-11-30","budget_amount":7500,"budget_currency":"TRY"}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "goal_contacts": 1,
    "starts_on": "string",
    "ends_on": "string",
    "budget": {
      "amount": 1,
      "currency": "USD"
    },
    "status": "scheduled",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z",
    "acquisition_links": 1,
    "invite_links": 1,
    "new_contacts": 1,
    "progress_percent": 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.
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Gets a growth campaign

GET/api/v1/growth-campaigns/{id}

The campaign's settings. The funnel and source comparison come from getGrowthCampaignReport. Scope: campaigns:read.

Scope
campaigns:read
SDK method
getGrowthCampaign · get_growth_campaign
MCP tool
getGrowthCampaignread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X GET "https://hiboty.com/api/v1/growth-campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "goal_contacts": 1,
    "starts_on": "string",
    "ends_on": "string",
    "budget": {
      "amount": 1,
      "currency": "USD"
    },
    "status": "scheduled",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z",
    "acquisition_links": 1,
    "invite_links": 1,
    "new_contacts": 1,
    "progress_percent": 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.
  • 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.

Updates a growth campaign

PATCH/api/v1/growth-campaigns/{id}

Only the given fields change; the result is validated with the create rules. budget_amount null removes the budget. Needs admin permission. Scope: campaigns:write.

Scope
campaigns:write
SDK method
updateGrowthCampaign · update_growth_campaign
MCP tool
updateGrowthCampaign

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Body fields

NameTypeRequiredDescription
namestringnolen 1–80
goal_contactsintegernoval 1–10000000
starts_ondateno
ends_ondateno
budget_amountnumber | nullnoval ≥ 0
budget_currencyenumnoTRY | USD | EUR

Example request

curl -X PATCH "https://hiboty.com/api/v1/growth-campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"goal_contacts":750,"ends_on":"2026-12-15"}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "goal_contacts": 1,
    "starts_on": "string",
    "ends_on": "string",
    "budget": {
      "amount": 1,
      "currency": "USD"
    },
    "status": "scheduled",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z",
    "acquisition_links": 1,
    "invite_links": 1,
    "new_contacts": 1,
    "progress_percent": 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.
  • 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.

Deletes a growth campaign

DELETE/api/v1/growth-campaigns/{id}

The campaign is deleted; linked acquisition and invite links, their counters and contacts' source data are kept. Needs admin permission. Scope: campaigns:write.

Scope
campaigns:write
SDK method
deleteGrowthCampaign · delete_growth_campaign
MCP tool
deleteGrowthCampaignirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X DELETE "https://hiboty.com/api/v1/growth-campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": 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.
  • 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.

Growth campaign funnel and source comparison

GET/api/v1/growth-campaigns/{id}/report

Funnel: tracked clicks (Hiboty /g/<code> button; Telegram does not report link clicks), starts, new contacts, ordering contacts, orders, payments and invite link joins. Clicks, starts and joins are lifetime link counters; new contacts are counted in the period and orders within 30 days of each contact's creation (same rule as getRevenueReport). Cost: amounts entered on links or imported (importReportCosts kind link); otherwise the budget. The same measures are returned per source. Scope: campaigns:read.

Scope
campaigns:read
SDK method
getGrowthCampaignReport · get_growth_campaign_report
MCP tool
getGrowthCampaignReportread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X GET "https://hiboty.com/api/v1/growth-campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6/report" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "campaign": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "goal_contacts": 1,
      "starts_on": "string",
      "ends_on": "string",
      "budget": {
        "amount": 1,
        "currency": "USD"
      },
      "status": "scheduled",
      "created_at": "2026-11-06T09:00:00.000Z",
      "updated_at": "2026-11-06T09:00:00.000Z",
      "acquisition_links": 1,
      "invite_links": 1,
      "new_contacts": 1,
      "progress_percent": 1
    },
    "range": {
      "from": "string",
      "to": "string"
    },
    "days_left": 1,
    "progress": {
      "new_contacts": 1,
      "goal_contacts": 1,
      "percent": 1,
      "remaining": 1
    },
    "funnel": {
      "clicks": 1,
      "starts": 1,
      "new_contacts": 1,
      "activated_contacts": 1,
      "orders": 1,
      "paid_orders": 1,
      "joins": 1,
      "leaves": 1
    },
    "rates": {
      "contacts_per_start": 1,
      "activation": 1,
      "paid_per_order": 1,
      "member_retention": 1
    },
    "revenue": {
      "orders": 1,
      "cancelled": 1,
      "refunded": 1,
      "gross": {
        "amounts": {
          "key": 1
        },
        "stars": 1
      },
      "net": {
        "amounts": {
          "key": 1
        },
        "stars": 1
      },
      "unpriced_items": 1
    },
    "spend": {
      "amount": 1,
      "currency": "USD",
      "mixed": {
        "key": 1
      }
    },
    "cost": {
      "amount": 1,
      "currency": "USD",
      "mixed": {
        "key": 1
      }
    },
    "cost_source": "spend",
    "budget_usage_percent": 1,
    "cost_per_contact": {
      "value": 1,
      "currency": "USD",
      "reason": "maliyet_yok"
    },
    "roi": {
      "value": 1,
      "reason": "maliyet_yok"
    },
    "acquisition_links": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "kind": "acquisition_link",
        "name": "Hiboty",
        "code": "ornek",
        "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "bot_name": "string",
        "url": "https://example.com/hook",
        "clicks": 1,
        "starts": 1,
        "new_contacts": 1,
        "activated_contacts": 1,
        "paid_orders": 1,
        "revenue": {
          "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
          }
        },
        "cost_per_contact": {
          "value": 1,
          "currency": "USD",
          "reason": "maliyet_yok"
        },
        "roi": {
          "value": 1,
          "reason": "maliyet_yok"
        }
      }
    ],
    "invite_links": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "kind": "invite_link",
        "name": "Hiboty",
        "community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "community_name": "string",
        "invite_link": "string",
        "joins": 1,
        "leaves": 1,
        "net_members": 1,
        "revoked": true,
        "expires_at": "2026-11-06T09:00:00.000Z"
      }
    ],
    "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.
  • 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.

Links a source to the campaign or opens a new link

POST/api/v1/growth-campaigns/{id}/sources

kind acquisition_link: source_id links an existing Telegram acquisition link, or bot_id + name (+ code) opens a new start link (t.me/<bot>?start=<code>). kind invite_link: source_id links an existing invite link, or community_id + name (+ member_limit, expires_in_days, join_request) opens a new invite link in Telegram. A link in another campaign is moved to this one. At most 50 sources per campaign. A Telegram error returns 502 channel_error. Needs admin permission. Scope: campaigns:write.

Scope
campaigns:write
SDK method
addGrowthCampaignSource · add_growth_campaign_source
MCP tool
addGrowthCampaignSourceexternal effect

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesID
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255

Body fields

NameTypeRequiredDescription
kindenumyesacquisition_link | invite_link
source_iduuidno
bot_iduuidno
community_iduuidno
namestringnolen ≤ 40
codestringnolen ≤ 32
member_limitinteger | nullnoval 1–99999
expires_in_daysinteger | nullnoval 1–365
join_requestbooleanno

Example request

curl -X POST "https://hiboty.com/api/v1/growth-campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6/sources" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"kind":"acquisition_link","bot_id":"00000000-0000-4000-8000-000000000001","name":"Instagram biyografi","code":"ig-bio"}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "kind": "acquisition_link",
    "name": "Hiboty",
    "code": "ornek",
    "url": "https://example.com/hook"
  }
}

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).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).channel_error

Removes a source from the campaign

DELETE/api/v1/growth-campaigns/{id}/sources/{source_id}

The link leaves the campaign; the link itself, the Telegram invite link and the counters are kept. Needs admin permission. Scope: campaigns:write.

Scope
campaigns:write
SDK method
removeGrowthCampaignSource · remove_growth_campaign_source
MCP tool
removeGrowthCampaignSourceirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID
source_idpathuuidyessource_id

Example request

curl -X DELETE "https://hiboty.com/api/v1/growth-campaigns/3fa85f64-5717-4562-b3fc-2c963f66afa6/sources/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": 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.
  • 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.