Skip to main content
The TGO Business API lets you send messages of four types — text, image, voice, and document — to any recipient that can be reached through TGO Connect. All messages are sent through the POST /api/v1/messages endpoint using an active sender number. Before sending, make sure you have at least one registered and verified sender number.
Sending messages requires the messages.send scope on your API key. Reading message logs requires messages.read. Make sure your key has the appropriate scopes for the operations you intend to perform.

​
Identify the sender

You can specify the sender either by phone number or by sender number ID.
Pass the sender_phone field with the full E.164 phone number of the registered sender:
{
  "sender_phone": "+201001187188",
  "to_phone": "+201010000000",
  "type": "text",
  "content": "Hello from TGO Business"
}
You must provide one of sender_phone or sender_number_id — not both.

​
Send a text message

Send a plain-text message using a JSON body: 
curl -X POST "https://{tenant-domain}/api/v1/messages" \
  -H "X-Api-Key: {api_key}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_phone": "+201001187188",
    "to_phone": "+201010000000",
    "type": "text",
    "content": "Hello from TGO Business"
  }'

​
Send a media message

For image, voice, and document messages, upload the file as multipart/form-data with the file attached in the media field: 
curl -X POST "https://{tenant-domain}/api/v1/messages" \
  -H "X-Api-Key: {api_key}" \
  -H "Accept: application/json" \
  -F "sender_phone=+201001187188" \
  -F "to_phone=+201010000000" \
  -F "type=image" \
  -F "media=@image.png"
For voice messages, include the duration field (in seconds, between 1 and 300): 
curl -X POST "https://{tenant-domain}/api/v1/messages" \
  -H "X-Api-Key: {api_key}" \
  -H "Accept: application/json" \
  -F "sender_phone=+201001187188" \
  -F "to_phone=+201010000000" \
  -F "type=voice" \
  -F "duration=45" \
  -F "media=@audio.ogg"

​
Check contact reachability

Before sending, verify that a recipient’s phone number exists in TGO Connect and can receive messages. This avoids failed sends and unnecessary API calls. 
curl "https://{tenant-domain}/api/v1/contacts/lookup?phone=+201010000000&sender_phone=+201001187188" \
  -H "X-Api-Key: {api_key}" \
  -H "Accept: application/json"
The response tells you whether the contact exists and is reachable: 
{
  "exists": true,
  "can_receive": true,
  "reason_code": "ok",
  "recipient_id": 4821,
  "is_verified": true,
  "phone_verified_at": "2025-01-10T08:00:00Z"
}
This endpoint requires the contacts.lookup scope.

​
Read message logs

Retrieve the history of messages sent from your organization: 
curl "https://{tenant-domain}/api/v1/messages" \
  -H "X-Api-Key: {api_key}" \
  -H "Accept: application/json"
Each entry in the response includes the message id, sender_number_id, message_type, content, status, and sent_at timestamp.

​
Check usage

Retrieve message usage grouped by sender number: 
curl "https://{tenant-domain}/api/v1/usage" \
  -H "X-Api-Key: {api_key}" \
  -H "Accept: application/json"
This endpoint requires the usage.read scope.