sendContact

Returns: Message⌨️ KeyboardsOfficial docs ↗

Use this method to send phone contacts. On success, the sent Message is returned.

Parameters

business_connection_idStringOptional

Unique identifier of the business connection on behalf of which the message will be sent

chat_idIntegerStringRequired

Unique identifier for the target chat or username of the target channel (in the format @channelusername)

message_thread_idIntegerOptional

Unique identifier for the target message thread (topic) of a forum; for forum supergroups and private chats of bots with forum topic mode enabled only

direct_messages_topic_idIntegerOptional

Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat

phone_numberStringRequired

Contact's phone number

first_nameStringRequired

Contact's first name

last_nameStringOptional

Contact's last name

vcardStringOptional

Additional data about the contact in the form of a vCard, 0-2048 bytes

disable_notificationBooleanOptional

Sends the message silently. Users will receive a notification with no sound.

protect_contentBooleanOptional

Protects the contents of the sent message from forwarding and saving

allow_paid_broadcastBooleanOptional

Pass True to allow up to 1000 messages per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot's balance

message_effect_idStringOptional

Unique identifier of the message effect to be added to the message; for private chats only

suggested_post_parametersSuggestedPostParametersOptional

A JSON-serialized object containing the parameters of the suggested post to send; for direct messages chats only. If the message is sent as a reply to another suggested post, then that suggested post is automatically declined.

reply_parametersReplyParametersOptional

Description of the message to reply to

reply_markupInlineKeyboardMarkupReplyKeyboardMarkupReplyKeyboardRemoveForceReplyOptional⌨️ Keyboards

Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user

Returns

On success, the Message object is returned.

GramIO Usage

Send a basic contact with a phone number and name using the context shorthand:

bot.on("message", async (ctx) => {
  await ctx.sendContact({
    phone_number: "+15551234567",
    first_name: "Alice",
    last_name: "Smith",
  });
});

Reply to the user's message while sending a contact:

bot.on("message", async (ctx) => {
  await ctx.replyWithContact({
    phone_number: "+15551234567",
    first_name: "Support Team",
  });
});

Send a contact with full vCard data for rich client-side import:

bot.on("message", async (ctx) => {
  const vcard = [
    "BEGIN:VCARD",
    "VERSION:3.0",
    "FN:Alice Smith",
    "TEL;TYPE=CELL:+15551234567",
    "EMAIL:alice@example.com",
    "ORG:Example Inc.",
    "END:VCARD",
  ].join("\n");

  await ctx.sendContact({
    phone_number: "+15551234567",
    first_name: "Alice",
    last_name: "Smith",
    vcard,
  });
});

Direct API call with bot.api.sendContact (useful outside message handlers):

const msg = await bot.api.sendContact({
  chat_id: 123456789,
  phone_number: "+15551234567",
  first_name: "Alice",
  last_name: "Smith",
});

Errors

Code	Error	Cause
400	Bad Request: chat not found	The chat_id is invalid, the bot has never interacted with the user, or the chat does not exist.
400	Bad Request: phone number is invalid	The phone_number string is empty or contains invalid characters. Include the country code (e.g. +1555...).
400	Bad Request: CONTACT_NAME_EMPTY	The first_name field is empty or missing. A non-empty first name is required.
403	Forbidden: bot was blocked by the user	The user blocked the bot. Remove them from your active user list.
429	Too Many Requests: retry after N	Flood control triggered. Back off for the specified number of seconds.

TIP

Use GramIO's auto-retry plugin to handle 429 errors automatically.

Tips & Gotchas

• phone_number is a free-form string. Telegram does not validate the phone number format server-side in detail, but clients display it as-is. Use standard international format (e.g. +15551234567) to ensure correct display and click-to-call behavior.
• The contact is not linked to a Telegram account. Even if the phone number belongs to a Telegram user, the contact message just shows the raw number. Users can choose to add it to their contacts manually.
• vcard enriches the contact card. Clients that support vCard can import additional fields (email, organization, address). Keep the vCard under 2048 bytes.
• last_name is optional but recommended. Many clients display the full name in the contact bubble. Providing both first and last names creates a cleaner contact entry.
• Note: sendContact takes a params object, not positional arguments. Unlike sendAnimation(animation, params?), you must pass all fields including phone_number inside a single object.

See Also

• Keyboards overview — attaching inline or reply keyboards
• Contact type — structure of the received contact object
• Message type — full structure of the returned message
• sendMessage — send plain text
• auto-retry plugin — handle rate limits automatically