python-telegram-bot/python-telegram-bot · error · ValueError

Either contact or phone_number and first_name must be passed

Error message

Either contact or phone_number and first_name must be passed as arguments.

What it means

Raised by Bot.send_contact when neither a Contact object nor both phone_number and first_name are provided. The library enforces this client-side because at least one complete contact specification is required to build the Telegram API request.

Source

Thrown at src/telegram/_bot.py:3587

                    |keyword_only_arg|
            reply_to_message_id (:obj:`int`, optional): |reply_to_msg_id|
                Mutually exclusive with :paramref:`reply_parameters`, which this is a convenience
                parameter for

                .. versionchanged:: 20.8
                    Bot API 7.0 introduced :paramref:`reply_parameters` |rtm_aswr_deprecated|

                .. versionchanged:: 21.0
                    |keyword_only_arg|
            contact (:class:`telegram.Contact`, optional): The contact to send.

        Returns:
            :class:`telegram.Message`: On success, the sent Message is returned.
        """
        # The contact parameter is a convenience functionality added by us, so enforcing the
        # mutual exclusivity here is nothing that Telegram would handle anyway
        if (not contact) and (not all([phone_number, first_name])):
            raise ValueError(
                "Either contact or phone_number and first_name must be passed as arguments."
            )
        if not bool(contact) ^ any([phone_number, first_name]):
            raise ValueError(
                "Either contact or phone_number and first_name must be passed as arguments. "
                "Not both."
            )

        if isinstance(contact, Contact):
            phone_number = contact.phone_number
            first_name = contact.first_name
            last_name = contact.last_name
            vcard = contact.vcard

        data: JSONDict = {
            "chat_id": chat_id,
            "phone_number": phone_number,
            "first_name": first_name,

View on GitHub (pinned to d3b69d2e9f)

Solutions

1. Pass a telegram.Contact object: send_contact(chat_id, contact=Contact('+1555...', 'John'))
2. Or pass both phone_number and first_name as keyword arguments
3. Check that both strings are non-empty before calling when data comes from optional input

Example fix

// before
await bot.send_contact(chat_id=chat_id, phone_number='+15550100')
// after
await bot.send_contact(chat_id=chat_id, phone_number='+15550100', first_name='John')

if contact is None and not (phone_number and first_name):
    raise ValueError('need contact or phone_number+first_name')
await bot.send_contact(chat_id, contact=contact, phone_number=phone_number, first_name=first_name)

When it happens

Trigger: Calling send_contact(chat_id, contact=None) with no phone_number/first_name, or passing only phone_number without first_name (the all() check requires both).

Common situations: Forwarding contact data from user input where fields may be empty; building a contact from optional form fields where first_name is blank.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Either contact or phone_number and first_name must be passed
• `current_offset` and `next_offset` are mutually exclusive!
• Cannot {action} an inaccessible message
• Can not create a mention to a private chat without first nam
• Can not create a mention to a public chat without title

AI-assisted analysis of python-telegram-bot/python-telegram-bot@d3b69d2e9f (2026-08-28). Data as JSON: /api/errors/e3e3377c06118b06. Report an issue: GitHub.