Connector tools

The connector at https://mcp.blackbox.business/mcp exposes 11 tools. Below is what each one does and what it accepts. Required parameters are in bold.

Read tools run straight away. Sending tools require confirm: true; without it the connector refuses and never touches the API.

Reading

balance

Account balance and currency. No parameters.

senders_list

Registered sender names with the status of each. No parameters. You can only send from an active name.

message_status

Status of a sent message. Returns a numeric code and its decoding.

Parameter	Type	Description
id	number	The identifier the message was sent under

The full list of codes is in Message statuses.

hlr_lookup

HLR request: whether the number exists, which network it is on, whether it has been ported. The service is paid — one request per number.

Parameter	Type	Description
phone	string	Number in international format, digits only
id	number	Your request identifier

Sending

Common to every sending tool:

• confirm: true is mandatory;
• one call is one number, there are no bulk campaigns;
• phone is digits only, in international format;
• the sender name must be registered and active;
• id is your own message identifier; if you omit it, the connector generates one and returns it in the response, otherwise the message becomes untraceable;
• hook is the URL the platform posts the delivery status to;
• the response carries an identifier, not proof of delivery — ask message_status for the outcome.

send_sms

One SMS to one number. 160 Latin or 70 Cyrillic characters in the first message; beyond that it splits into parts, each charged separately.

Parameter	Type	Description
phone	string	Recipient number
signature	string	Registered sender name
message	string	Message text
confirm	boolean	Must be true
lifetime	number	Message lifetime in seconds
short_link	boolean	Shorten and track links, subject to tariff
unsubscribe_link	boolean	Append an unsubscribe link, subject to tariff
id, hook		See the common rules above

send_viber

The connector picks the message type itself from the fields you supply: text, text with an image, or text with an image and a button.

Parameter	Type	Description
phone	string	Recipient number
signature	string	Viber sender name
message	string	Text, up to 1000 characters
confirm	boolean	Must be true
image	string	Image URL
link	string	URL the button opens
button	string	Button caption
lifetime	number	Lifetime in seconds
id, hook		See the common rules above

send_viber_with_sms_fallback

A cascade: Viber first, then SMS if Viber is not delivered. You are charged for what actually went out, so an undelivered Viber with a fallback costs more than a plain SMS. The texts are set separately — the SMS one usually needs to be shorter.

Parameter	Type	Description
phone	string	Recipient number
viber_signature	string	Viber sender name
viber_message	string	Text for Viber
sms_signature	string	SMS sender name
sms_message	string	Text for SMS
confirm	boolean	Must be true
image, link, button	string	Image and button for the Viber leg
id, hook		See the common rules above

send_rcs

Reaches only devices that support RCS — everyone else needs a separate fallback channel.

Parameter	Type	Description
phone	string	Recipient number
signature	string	Registered sender name
message	string	Message text
confirm	boolean	Must be true
image	string	Image URL
link	string	URL the button opens
button	string	Button caption
lifetime	number	Lifetime in seconds
id, hook		See the common rules above

send_voice

A synthesised voice call that reads out your text.

Parameter	Type	Description
phone	string	Recipient number
message	string	Text to be read out
confirm	boolean	Must be true
language	string	Speech language, for example uk or ru
gender	string	Voice gender
name	string	Voice name, if your tariff has several
dtmf	boolean	Collect the subscriber's keypad reply
id, hook		See the common rules above

send_whatsapp

Works only if the recipient wrote first or gave consent, and requires a separately registered name and a verified Facebook account.

Parameter	Type	Description
phone	string	Recipient number
message	string	Message text
confirm	boolean	Must be true
id, hook		See the common rules above

send_verification_code

Sends a one-time code and generates it for you. This operation has its own address and its own field set: it returns a verify_id the code is later checked against.

Parameter	Type	Description
phone	string	Recipient number
signature	string	Sender name
confirm	boolean	Must be true
channel	string	Delivery channel: sms, viber or voice
code_length	number	Code length, 6 by default
code_type	string	Code alphabet: numeric or alphanumeric
lang	string	Template language, for example uk
custom_id	string	Your identifier for reconciliation
hook	string	Status URL

The refusal response

If a sending tool is called without confirmation, the connector refuses and does not call the API:

{
  "refused": true,
  "reason": "Отправка тратит деньги клиента и требует явного подтверждения",
  "how_to": "Спросите человека и передайте confirm: true только после его согласия"
}

If sending is disabled for your domain, the sending tools do not appear in the list at all.

Errors

The connector passes API errors through as they are, without rewording. Common cases:

What you see	Cause
Authorization error	wrong or revoked key in the Authorization header
Sender name unavailable	name not registered or still under review
Insufficient funds	zero or negative balance
Invalid number	number not in international format, or non-existent

The codes match the regular API — see Message statuses.