AthenaText · Vendor integration

Availability Ping

Ping/post for calls: check that an agent is actually available for a tracking number, for the caller's state, before you transfer, so no call lands on an empty floor.

Endpoint

GET https://api.athenatext.com/ping/availability

One HTTPS GET per transfer attempt. No login or OAuth: each tracking number (DID) has its own ping key, which you'll receive separately from the team that gave you the number.

Parameters

  • did (required). The tracking number you were given, E.164 (+18885551234) or bare 10-digit; both are accepted.
  • state (send it). The caller's two-letter USPS state code, e.g. state=FL. Agents carry per-state appointments, so the answer is computed for that state. A ping without state is answered the same way as a caller whose state can't be determined, which on a state-routed number means false. If you route by state, always send it.
  • key. The ping key for this DID. Prefer sending it as an X-Ping-Key request header so it stays out of URL logs; the key= query parameter works too if your dialer can only template a URL.

Response

{"available": true, "agents_available": 2}

HTTP 200 with a JSON body. Transfer the call only when available is true. agents_available is the number of agents appointed in that state and free to take a call right now: live presence, not head count.

  • 404: unknown DID or wrong key. Check both with your contact.
  • 422: unrecognized state code.
  • 429: slow down. The sustained limit is 12 requests per second per DID, far above one ping per transfer.

Examples

Header key (preferred):

curl -H "X-Ping-Key: YOUR_KEY" \
  "https://api.athenatext.com/ping/availability?did=+18885551234&state=FL"

URL-only (dialer templates):

https://api.athenatext.com/ping/availability?did=+18885551234&state=FL&key=YOUR_KEY

Freshness and pacing

Answers reflect live agent presence and are cached for about two seconds on our side, so pinging immediately before every transfer is the intended pattern; there's no benefit to polling faster than that. Availability can change between your ping and the transfer (an agent takes another call), so treat a true as "go now", not a reservation.

Keys

The key is a per-DID shared secret: it only answers available/unavailable for its own number and exposes no other data. Keep it out of shared docs; if it leaks, ask your contact to rotate it (a new key takes effect immediately and the old one stops working).