##################################
# Sender.Services API entrypoint #
##################################

GENERAL INFORMATION

This API provides raw statistics for your agency in JSON format.

Prerequisites:
1. Go to your agency panel: https://sender.services/agency/settings
2. In the settings, specify the IPv6 address from which you will make API requests.

Rate limits and constraints:
- Rate limit: 1 request every 2 seconds
- Maximum items per page: 500
- Response format: JSON

If a request fails, the API returns an HTTP status code and may include a JSON body with an error message.

Common errors:
- 403 Forbidden: the IPv6 address used for the request is not registered in your agency settings
- 429 Too Many Requests: you have exceeded the rate limit (1 request per 2 seconds)
- 400 Bad Request: a required parameter is missing or malformed


API ENDPOINTS

List of agency accounts
=======================
Purpose: retrieves a list of all accounts associated with a specific agency.

Endpoint format:
/api.php?accounts=AGENCY_LOGIN

Query parameters:
- accounts — agency login (identifier), required

Example:
/api.php?accounts=phalcon


########################################
# Information about a specific account #
########################################

To retrieve information about a specific account, the request must contain the following mandatory query parameters:
- name   — account identifier
- plugin — dot-separated site and section identifier

Example:
/api.php?name=C123456&plugin=charmdate.chat

Information about time online
=============================
Purpose: retrieves the online activity periods for the account on a given date.

Query parameters:
- online — date for which to retrieve online activity (format: YYYY‑MM‑DD). If empty, data for the current day is returned.

Pagination:
If the result contains more than 500 items, the response includes a "more" flag. To retrieve subsequent pages, add the "page" parameter:
page — page number to retrieve (default is 1). Use page=2, page=3, etc.

Examples:
- Get online activity for May 25, 2025:
  /api.php?name=C123456&plugin=charmdate.chat&online=2025-05-25
- Get the second page of results (if "more": true in the first response):
  /api.php?name=C123456&plugin=charmdate.chat&online=2025-05-25&page=2

Response structure (JSON):
{
  "items": [
    [
      "2025-05-25 08:30:00",  // Check‑in time (YYYY-MM-DD HH:II:SS format)
      "2025-05-25 10:45:00",  // Check‑out time (YYYY-MM-DD HH:II:SS format)
      "2001:db8::1"             // IP address
    ]
    // ... more periods
  ],
  "more": true  // Boolean flag: true if more data is available
}

Field descriptions:
- items: array of online activity periods. Each period is an array with:
  - [0] Check‑in: datetime when the account came online
  - [1] Check‑out: datetime when the account went offline
  - [2] IP address: IP address associated with this session
- more — boolean flag. If true, there are more than 500 records. Make another request with page=N+1 to get the next page.


Information about sent messages
===============================
Purpose: retrieves information about messages sent by the account on a specific date.

Query parameter:
- messages — date for which to retrieve message statistics (format: YYYY-MM-DD). If empty, data for the current day is returned.

Pagination:
If the result contains more than 500 unique message texts, the response includes a "more" flag. To retrieve the next page, add:
page — page number to retrieve (e.g. page=2)

Examples:
- Get sent messages for May 25, 2025:
  /api.php?name=C123456&plugin=charmdate.chat&messages=2025-05-25
- Get the second page of results:
  /api.php?name=C123456&plugin=charmdate.chat&messages=2025-05-25&page=2

Response structure:
{
  "items": [
    {
      "text": "Hello, how are you?",
      "sent": 12,
      "replies": 3,
      "reactions": {}
    },
    {
      "text": "Nice to meet you!",
      "sent": 8,
      "replies": 1,
      "reactions": {}
    }
    // ... more message entries
  ],
  "more": false  // Boolean flag: true if additional pages exist
}

Field descriptions:
- items: array of message objects. Each object contains:
  - text — text of the sent message
  - sent — number of times this message was sent
  - replies — number of replies received for this message
  - reactions - plugin specific data
- more — boolean flag. If true, not all messages are included in this response. Use the "page" parameter to fetch the next batch.


#####################################
# Information about accounts online #
#####################################
Purpose: retrieves state information about accounts that are currently online.

Endpoint format:
/api.php?girls-online=AGENCY_LOGIN

Query parameters:
- girls-online — login of your agency (identifier), required

Response structure:
{
  "items": [
    {
      "site": "dating",
      "name": 123456,
      "comment": "",
      "section: "chat",
      "state": []
    },
    // ... more entries
  ],
}

Field descriptions:
- items: array of objects representing online accounts. Each object contains:
  - site — identifier of the site (e.g. dating)
  - name — account identifier
  - comment — comment from the agency panel for this account
  - section — identifier of site section (chat or mail)
  - state — site-specific array of data; the structure differs for each site. Details can be clarified via our support team.

############################
#       Chat history       #
# (manually sent messages) #
############################

Supported sites:
We collect chat history only for the following sites: allcreate, amaldate, amolatina, arabiandate, dating, dream, findbride, girlsonly, global, guysonly, hotti, jump, ladadate, prime_date, romance, svadba, udate.

Information only about manually sent messages
=============================================
Purpose: retrieves messages manually sent by agency accounts to their interlocutors for 24 hours.

Endpoint format:
/api.php?sent2chat=SITE&agency=AGENCY_LOGIN

Query parameters:
- sent2chat — identifier of the supported site (e.g. dating), required
- agency — login of your agency (identifier), required

Example:
/api.php?sent2chat=dating&agency=Phalcon

Pagination:
If the result contains more than 500 messages, the response includes a "more" flag. To retrieve the next page, add:
page — page number to retrieve (e.g. page=2)

Response structure:
{
  "items": [
    {
      "girl": 123456,
      "man": 7890,
      "date": "2025-05-25 14:22:10",
      "message": "Hi, I liked your profile!"
    },
    // ... more message entries
  ],
  "girls": [
    {
      "id": 123456,
      "comment": "Newcomer"
    }
    // ... more sender entries (if available)
  ],
  "more": true  // Boolean flag: true if additional pages exist
}

Field descriptions:
- items: array of message objects. Each object contains:
  - girl — ID of the sender (account from your agency)
  - man — ID of the recipient (interlocutor on the site)
  - date — timestamp when the message was sent
  - message — text content of the message
- girls: optional array with additional agency-side information about senders. Each object contains:
  - id — matches the "girl" field, identifies the sender
  - comment — internal comment set in the agency panel for this account
- more — boolean flag. If true, there are more messages to retrieve. Use the "page" parameter to get the next page.

Chat history for a specific account 
===================================
Purpose: retrieves full chat history between a specific agency account and its interlocutors.

Endpoint format:
/api.php?chat_of=SITE&name=ID

Query parameters:
- chat_of — identifier of the supported site (e.g. dating), required
- name - ID of the agency account, required
- interlocutor - ID of the interlocutor, optional. If provided, returns messages only with this person.
- since - minimum date for messages (format: YYYY-MM-DD), optional. Returns messages sent on or after this date, if omited yesterday date or 1 day before before will be used.
- before - maximum date for messages (format: YYYY-MM-DD), optional. Returns messages sent before this date, if omited 1 day after since will be used.

Example:
/api.php?chat_of=dating&name=12345&interlocutor=67890&since=2026-05-01&before=2026-05-25

Pagination:
If the result contains more than 500 messages, the response includes a "more" flag. To retrieve the next page, add:
page — page number to retrieve (e.g. page=2)

Response structure:
{
  "items": [
    {
      "girl": 123456,
      "man": 7890,
      "date": "2025-05-25 14:22:10",
      "message": "Hi, I liked your profile!",
      "direction: "out"
    },
    {
      "girl": 123456,
      "man": 7890,
      "date": "2025-05-25 14:25:05",
      "message": "Wow!",
      "direction: "in"
    },
    // ... more message entries
  ],
  "comment": "Newcomer"
  "more": true  // Boolean flag: true if additional pages exist
}

Field descriptions:
- items: array of message objects. Each object contains:
  - girl — ID of the sender (agency account)
  - man — ID of the interlocutor
  - date — timestamp when the message was sent (format: YYYY-MM-DD HH:MM:SS)
  - message — text content of the message
  - direction — message direction: "in" (received by the agency account), "out" (sent by the agency account)
- comment — internal comment set in the agency panel for this account (if available)
- more — boolean flag. If true, there are more messages to retrieve. Use the "page" parameter to get the next page.